@fusion.dev/helix-templates 0.34.1 → 0.35.0

package/README.md

@@ -14,8 +14,15 @@ written against.
 
 | Template | What it is |
 |---|---|
-| `react-vite` | React and TypeScript on Vite. The shortest path to a running component. |
-| `react-nextjs` | React and TypeScript on the Next.js App Router, elements registered once. |
+| `react-vite` | React and TypeScript on Vite. The shortest path to a running app. |
+| `react-nextjs` | React and TypeScript on the Next.js App Router, the three pages as real routes. |
+
+Both lay down the same three pages, in the same order and with the same copy: a
+landing page saying what is installed and where it is documented, an overview
+holding a sorted, paged, selectable data table, and a form whose controls a
+`<form>` reads with `FormData` because they are real form participants. What
+differs between them is what the framework forces, which is what makes them
+worth diffing against each other.
 
 **There is no build-free HTML template**, and that is a fact about the packages
 rather than an omission. `@fusion.dev/helix`'s published entry re-exports bare

package/dist/index.js

@@ -1,14 +1,14 @@
 export const 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'],
+        named: ['index.html', 'package.json', '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', 'package.json'],
+        named: ['app/layout.tsx', 'app/site-header.tsx', 'package.json'],
         title: 'React (Next.js)',
     },
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-templates",
   "description": "Starter templates for Helix, as data. Read by `helix new` and by `npm create @fusion.dev/helix-app`.",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {

package/templates/react-nextjs/app/app.css

@@ -0,0 +1,363 @@
+/*
+ * The page around the components.
+ *
+ * Helix draws its own insides, so what is left to an app stylesheet is the
+ * measure, the rhythm between blocks, and the few things a component
+ * deliberately leaves open. Everything below is a Helix token or a documented
+ * hook, so a theme moves it and both color modes follow without a second copy
+ * of anything.
+ *
+ * **Color appears twice and both places are named.** The wordmark takes
+ * `--helix-color-brand-mark`, which is the token for the brand as a graphic
+ * rather than as a word, and a chosen row takes `--helix-color-primary-subtle`
+ * through the parts the table publishes. Everywhere else this page is ink on the
+ * background and the components carry their own.
+ */
+
+/*
+ * **The shell, and what stops a short route ending in a void.** The overview is
+ * a header, a table and a caption, which on a 1280 by 900 window left something
+ * like four hundred pixels of nothing under it: a page that stopped rather than
+ * a page that finished. A column the height of the window with the footer at the
+ * end of it puts a floor under every route.
+ *
+ * **Flex and not grid, because the bar is sticky.** A grid item's containing
+ * block is its own grid area, which is one row as tall as the bar, so a sticky
+ * header in a grid row sticks for nothing. A flex item's containing block is the
+ * flex container, which is the whole document.
+ */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 100dvh;
+}
+
+/*
+ * **56rem, which is a measure rather than a maximum.** A page is as wide as its
+ * widest block can be read at, and the widest block here is a four-column table:
+ * given the whole of a 1280 window its first column came out 448 pixels across
+ * to hold a name, which reads as a table that has been stretched rather than
+ * laid out. The bar and the footer are centered in the same width, so the
+ * wordmark sits over the first column of the page rather than near it.
+ *
+ * `flex-grow` is what hands the slack to the page rather than to the footer.
+ */
+.page {
+  flex-grow: 1;
+  margin-inline: auto;
+  max-inline-size: 56rem;
+  padding-block: var(--helix-space-2xl) var(--helix-space-3xl);
+  padding-inline: var(--helix-space-lg);
+}
+
+/*
+ * Two documented hooks, and both are about agreeing with the page. The bar
+ * centers its row in the page's measure, so the wordmark sits over the first
+ * column rather than near it. And it draws no line under itself by default,
+ * because a header over a page that already has a surface does not need one:
+ * this page has no such surface, so it asks for one. A token rather than a
+ * color, so it follows the theme.
+ */
+helix-app-header {
+  --app-header-border-color: var(--helix-color-border);
+  --app-header-max-inline-size: 56rem;
+}
+
+/* The mark beside the project's name, which is the one graphic on the page and
+   the reason `--helix-color-brand-mark` exists: a mark answers to the 3:1 WCAG
+   asks of a graphic rather than to the 4.5 a word does, so it may sit closer to
+   the brand a theme was seeded with than any text color can. Swap the glyph, or
+   replace the whole element with your own logo. */
+.wordmark {
+  align-items: center;
+  display: inline-flex;
+  gap: var(--helix-space-xs);
+}
+
+.wordmark helix-icon {
+  color: var(--helix-color-brand-mark);
+}
+
+/*
+ * One rhythm between the blocks of a page, so no page states its own.
+ *
+ * **`minmax(0, 1fr)` and never a bare column, which is the trap in every grid
+ * here.** An implicit track is `auto`, and an `auto` track's minimum is its
+ * content's min-content size, so a child that would rather scroll itself widens
+ * the track instead and takes the page with it. Measured at 320: the table's
+ * columns floor at 344, the column it sits in should have been 288, and
+ * `documentElement.scrollWidth` came back 360 against a 320 viewport. The whole
+ * page scrolled sideways so that a table with its own scrollport would not have
+ * to. Zero as the minimum hands the overflow back to whoever is equipped for it.
+ */
+.stack,
+.section,
+.hero,
+.first-screen,
+.fact,
+.facts,
+.notes,
+.split {
+  grid-template-columns: minmax(0, 1fr);
+}
+
+/* One step between the blocks of a page and a smaller one inside them, which is
+   the whole of the rhythm: `3xl` here against the `md` a section puts between
+   its heading and its block, so a reader sees three groups rather than six
+   evenly spaced things. */
+.stack {
+  display: grid;
+  gap: var(--helix-space-3xl);
+}
+
+/*
+ * **The first screen is two things at once**, which is what makes it a screen
+ * rather than a stack: what this is, on the left, and the library doing it, on
+ * the right. Below 60rem there is no room for two columns that are both worth
+ * reading, so they become one and the panel reads as the thing the words were
+ * about.
+ *
+ * `start`, because a grid column stretches to its tallest sibling: the panel
+ * beside a taller block of words would otherwise grow to match it and spread its
+ * own regions out to fill the difference.
+ */
+.first-screen {
+  align-items: start;
+  display: grid;
+  gap: var(--helix-space-xl);
+}
+
+@media (width >= 60rem) {
+  .first-screen {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 20rem);
+  }
+}
+
+/* A heading and the lines around it are one block, and the gap between them is
+   not the gap between blocks. Every route opens with one. */
+.hero {
+  display: grid;
+  gap: var(--helix-space-xs);
+  justify-items: start;
+}
+
+/* **A measure for the lede, which the page's own is too wide to be.** A line of
+   prose across 56rem is around 110 characters, and the readable range tops out
+   near 75. The heading above it is exempt: a heading is scanned rather than
+   read along. */
+.lede {
+  max-inline-size: 42rem;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--helix-space-sm);
+  padding-block-start: var(--helix-space-md);
+}
+
+/*
+ * **The panel is the library rather than a picture of it**, so the only thing it
+ * needs from here is room. Two documented hooks: the figures come down a step
+ * from the display size, which is set for a figure on its own and is too loud
+ * for three of them in a 20rem column, and the rule between them comes in from
+ * `2xl`, which `divided` doubles and which would leave no column to put a
+ * number in.
+ */
+.specimen {
+  --stat-group-gap: var(--helix-space-md);
+  --stat-value-size: var(--helix-text-xl);
+}
+
+/* A section is its heading and its one block, closer together than two sections
+   are. */
+.section {
+  display: grid;
+  gap: var(--helix-space-md);
+}
+
+/*
+ * **Three facts about the library, and deliberately not three cards.** A row of
+ * identical outlined boxes is the shape a generated page takes, and it is also a
+ * claim: a box says each of these is its own object, when they are three
+ * paragraphs about the same installed thing. A rule over each column groups them
+ * at a fraction of the weight, and leaves the cards below to mean something,
+ * which is that they go somewhere.
+ *
+ * `border-thick` in the foreground rather than a hairline in the border color:
+ * this is a heading device rather than a container edge, and it is the one place
+ * the page draws in ink.
+ */
+.facts {
+  display: grid;
+  gap: var(--helix-space-lg);
+}
+
+@media (width >= 48rem) {
+  .facts {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+.fact {
+  align-content: start;
+  border-block-start: var(--helix-border-thick) solid var(--helix-color-foreground);
+  display: grid;
+  gap: var(--helix-space-xs);
+  justify-items: start;
+  padding-block-start: var(--helix-space-sm);
+}
+
+/*
+ * **The one departure the grids state.** `helix-grid` takes a fixed count as
+ * plain CSS, which is what keeps a server-rendered row of cards correct before
+ * any JavaScript arrives. Below this width there is only ever room for one
+ * column, and `--grid-columns` is the documented way to say so from outside the
+ * shadow root.
+ */
+@media (width < 48rem) {
+  helix-grid {
+    --grid-columns: minmax(0, 1fr);
+  }
+}
+
+/*
+ * **The cards keep `start`, which is `--card-align`'s resting value, and the
+ * alternative is worth naming because it looks right and is not.**
+ * `space-between` puts the last line of each card on its bottom edge, so a row
+ * of cards ends in a straight line. It gets there by sharing the slack out
+ * between every region, and the first thing that moves is the body: three cards
+ * of six, five and seven lines had their opening lines 50 pixels apart under
+ * headings that were level. A reader scans the first line of each, so that is
+ * the alignment worth keeping.
+ */
+
+/* The card fills the link that wraps it, so a row of destinations ends level:
+   the anchor is the grid item and stretches, and the card inside it does not.
+   The regions stay packed at the top, per `--card-align` above. */
+[data-card] > helix-card {
+  block-size: 100%;
+}
+
+/* A form is read straight down, and a field wider than about this stops being
+   scannable however much room the window has. */
+.form {
+  align-content: start;
+  display: grid;
+  gap: var(--helix-space-lg);
+  justify-items: start;
+  max-inline-size: 28rem;
+}
+
+/* Every control fills the column; the submit is as wide as its own words. */
+.form > :not(helix-button) {
+  inline-size: 100%;
+}
+
+/*
+ * **The form takes a column and the notes take the rest.** A 28rem form on a
+ * 1280 window is a third of a page and two thirds of nothing, which is what the
+ * measure above cannot fix on its own: the form has a right width and the page
+ * does not shrink to it. Narrow, the two stack and the notes read as a
+ * postscript, which is the order they are written in.
+ */
+.split {
+  display: grid;
+  gap: var(--helix-space-2xl);
+}
+
+@media (width >= 60rem) {
+  .split {
+    grid-template-columns: minmax(0, 28rem) minmax(0, 1fr);
+  }
+}
+
+/* `start`, because a grid column stretches to its tallest sibling and a
+   stretched grid shares the difference out between its own rows: beside a form
+   half a page long, three paragraphs came out 140 pixels apart. */
+.notes {
+  align-content: start;
+  display: grid;
+  gap: var(--helix-space-sm);
+  justify-items: start;
+  max-inline-size: 32rem;
+}
+
+/* The callout takes the column, which `start` above would otherwise size to its
+   own words: a notice narrower than the paragraph under it reads as a stray. The
+   link beside it is meant to be its own width. */
+.notes > helix-callout {
+  inline-size: 100%;
+}
+
+/*
+ * **The counterpart to the bar, and the reason every route now ends rather than
+ * stops.** The rule runs the window while its contents keep the page's measure,
+ * which is what a footer under a centered page looks like; the shell above is
+ * what holds it to the bottom of a window a route does not fill.
+ */
+.site-footer {
+  border-block-start: var(--helix-border-thin) solid var(--helix-color-border);
+}
+
+.footer-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--helix-space-md);
+  justify-content: space-between;
+  margin-inline: auto;
+  max-inline-size: 56rem;
+  padding-block: var(--helix-space-lg);
+  padding-inline: var(--helix-space-lg);
+}
+
+.footer-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--helix-space-md);
+}
+
+/*
+ * **Narrow, the gutter gives before the content does.** 24 pixels either side of
+ * a 390 window is 48 of 390 spent on margin, and the table needs 355 of what is
+ * left. At `md` it has 358 and fits; at `lg` it was 13 pixels short and the last
+ * column sat outside the box until the reader scrolled the table sideways.
+ */
+@media (width < 40rem) {
+  .page {
+    padding-block: var(--helix-space-xl) var(--helix-space-2xl);
+    padding-inline: var(--helix-space-md);
+  }
+
+  .footer-row {
+    padding-inline: var(--helix-space-md);
+  }
+}
+
+/*
+ * **The escape hatch, and the reason a component names its parts.** The table
+ * washes a chosen row at the strength `Tag` rests at; this page wants a row
+ * somebody has ticked to be findable from across the screen, and there is no
+ * token for "more than that". `::part` reaches the boxes the component drew
+ * without forking it, and a rule written out here beats the component's own
+ * however specific that one is.
+ *
+ * **Two parts and not one, because a row has no box.** The row is
+ * `display: contents` so that one grid can align every column across every row,
+ * which leaves the cells as the only thing a selection can be painted on. The
+ * table names both: the data cells and the cell holding the checkbox. Naming
+ * only the first leaves a pale stripe down the left of every chosen row.
+ *
+ * The values are still the library's, so a theme carries them like everything
+ * else. `primary-subtle` and not `primary-surface`: the second is the solid
+ * accent a button stands on and expects white on top of it, so a row painted
+ * with it puts the table's own ink on a saturated fill.
+ */
+helix-data-table::part(cell-selected),
+helix-data-table::part(select-selected) {
+  background-color: var(--helix-color-primary-subtle);
+}
+
+helix-data-table::part(cell-selected) {
+  font-weight: var(--helix-weight-semibold);
+}

package/templates/react-nextjs/app/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/react-nextjs/app/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',
+  /** React specifically: properties, events, and the server boundary. */
+  react: 'https://fusion.dev/helix/docs/react',
+  /** 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/react-nextjs/app/join/page.tsx

@@ -0,0 +1,12 @@
+import { SignupForm } from '../signup-form'
+
+/**
+ * A real route under `app/`, which is what the App Router gives you and the Vite
+ * template has to stand in for with a hash.
+ *
+ * The page itself is still a server component: the form is the client component,
+ * because the form is the part with handlers on it.
+ */
+export default function Page() {
+  return <SignupForm />
+}