@fusion.dev/helix-templates 0.34.2 → 0.35.0

package/templates/react-nextjs/app/landing.tsx

@@ -0,0 +1,191 @@
+import Link from 'next/link'
+import { roster } from './data'
+import { DOCS } from './docs'
+
+/**
+ * **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-nextjs/app/layout.tsx

@@ -4,12 +4,17 @@ import type { ReactNode } from 'react'
 /* Every layer in one import: the tokens, the reset, the utility layer, and the
    `:not(:defined)` rules that keep a tag from arriving unstyled. */
 import '@fusion.dev/helix-styles/helix.css'
+/* After it, so a rule of your own that names the same thing wins. */
+import './app.css'
 
 /* Extensionless, unlike the libraries this imports. Turbopack does not map a
    `.js` specifier back to the `.tsx` beside it, which is webpack's
    `extensionAlias` and has no equivalent there, so `./helix-elements.js` fails
-   the first `next build` with "Module not found". */
+   the first `next build` with "Module not found". Every local import in this
+   template is written the same way for that reason. */
 import { HelixElements } from './helix-elements'
+import { SiteFooter } from './site-footer'
+import { SiteHeader } from './site-header'
 
 export const metadata: Metadata = { title: '__PROJECT_NAME__' }
 export const viewport: Viewport = { initialScale: 1, width: 'device-width' }
@@ -30,7 +35,14 @@ export default function RootLayout({ children }: { children: ReactNode }) {
     <html lang="en">
       <body>
         <HelixElements />
-        {children}
+        {/* The bar, the route and the footer, in a column the height of the
+            window. `app.css` says why the footer is worth having and why the
+            column is flex. */}
+        <div className="shell">
+          <SiteHeader />
+          <main className="page">{children}</main>
+          <SiteFooter />
+        </div>
       </body>
     </html>
   )

package/templates/react-nextjs/app/overview/page.tsx

@@ -0,0 +1,23 @@
+import { Overview } from '../overview'
+
+/**
+ * A server component, rendering custom elements directly.
+ *
+ * **The rows cross the boundary as a plain array**, which is worth saying because
+ * React drops object and function props on both halves of a server render: the
+ * server writes nothing for a prop whose value is an object, and the hydrate path
+ * applies none either. `HelixElement` assigns them itself once it upgrades, so
+ * the data view takes its data as an ordinary prop and this page needs no
+ * `'use client'`.
+ *
+ * **The cell values still do not server-render**, which is a different limit.
+ * Reading a cell needs the columns, and the columns are markup children the
+ * server render does not hand the table, so the first paint is a labeled shell.
+ * Reach for `helix-table` where the values have to be in the served HTML.
+ *
+ * What never crosses is a handler. Anything with one is a client component, the
+ * same as in any other React app, which is what `signup-form.tsx` is.
+ */
+export default function Page() {
+  return <Overview />
+}

package/templates/react-nextjs/app/overview.tsx

@@ -0,0 +1,91 @@
+import { members } from './data'
+import { DOCS } from './docs'
+
+/**
+ * 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-nextjs/app/page.tsx

@@ -1,18 +1,13 @@
+import { Landing } from './landing'
+
 /**
- * A server component, rendering custom elements directly.
+ * The page a scaffold opens on, and a server component like the two beside it.
  *
- * Helix events are props: `onhelix-before-change` reaches `helix-before-change`.
- * Anything needing a handler is a client component, the same as any other React
- * app: this page needs none.
+ * Nothing here has a handler, so nothing here is marked `'use client'`. That is
+ * the line in an App Router project and it is not about Helix: the elements are
+ * registered once from the layout, and an unregistered tag in the served HTML is
+ * only an unknown element, which upgrades the moment the definition lands.
  */
 export default function Page() {
-  return (
-    <helix-flex align="center" direction="column" gap="lg">
-      <helix-text as="h1">__PROJECT_NAME__</helix-text>
-      <helix-text>Edit `app/page.tsx` and save.</helix-text>
-      <helix-button emphasis="solid" tone="primary">
-        Get started
-      </helix-button>
-    </helix-flex>
-  )
+  return <Landing />
 }

package/templates/react-nextjs/app/signup-form.tsx

@@ -0,0 +1,171 @@
+'use client'
+
+/*
+ * **A handler is what makes this a client component.** A server component's
+ * output is serialized and a function cannot be, so anything with an `onSubmit`
+ * or an `onhelix-*` prop lives on this side of the line. The data view next door
+ * has neither, so it stays a server component.
+ */
+
+import { type FormEvent, useState } from 'react'
+import { teams } from './data'
+import { DOCS } from './docs'
+
+/** 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-nextjs/app/site-footer.tsx

@@ -0,0 +1,38 @@
+import { DOCS } from './docs'
+
+/**
+ * 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>
+  )
+}