@fusion.dev/helix-templates 0.139.0 → 0.140.0

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.139.0",
+  "version": "0.140.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {

package/templates/angular/src/app/data.ts

@@ -2,39 +2,40 @@
  * 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.
+ * Point `rows` at whatever you fetch and the table stays the same: it takes the
+ * whole result and does the sorting, the filtering, and the paging itself. Past
+ * the size a browser can hold, `mode="server"` hands the paging to you, one page
+ * at a time.
  */
 
 /**
  * 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.
+ * **A type alias, which TypeScript makes load-bearing here.** `rows` takes
+ * `Readonly<Record<string, unknown>>`, and an interface has no implicit index
+ * signature, so an interface of exactly these fields is not assignable to it.
+ * The error names the index signature, 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.
+   * With one, a sort moves each row's element whole, so focus and anything
+   * attached to a row go with it. Without one, a sort rewrites the cells in
+   * place and loses both.
    */
   readonly id: string
   /**
-   * What the reader is here to find.
+   * The name a row is found by.
    */
   readonly name: string
   /**
-   * A number rather than a formatted string, so the column sorts by size.
+   * A number, 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.
+   * the value underneath is, which is cheap to get right now and expensive to
+   * add later.
    */
   readonly reviews: number
   /**
@@ -68,8 +69,7 @@ export const teams: readonly string[] = [...new Set(members.map((one) => one.tea
 /**
  * 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.
+ * Derived from the rows, so the panel and the table always agree.
  */
 export const roster = {
   /** How many rows the data view has. */

package/templates/angular/src/app/docs.ts

@@ -1,13 +1,13 @@
 /**
- * The documentation this starter links to.
+ * The documentation the 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.
+ * **One module, because links are what rots first in a starter.** A page that
+ * composes its own URLs ships a plausible-looking 404 to every project
+ * scaffolded from it, and it shows only when the link is followed. Here they
+ * are in one list you 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.
+ * Checked October 4, 2026: every entry answers 200.
  */
 export const DOCS = {
   /** Angular specifically: the schema, property bindings, and events. */
@@ -16,9 +16,9 @@ export const DOCS = {
   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. */
+  /** 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. */
+  /** The light and dark pair, and the attribute that sets which one shows. */
   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',

package/templates/angular/src/app/landing.html

@@ -1,11 +1,14 @@
 <header class="first-screen">
+  <!-- **The light behind the first screen**: a helix, drawn by the library in
+       the theme's colors, so a new brand color relights it. It shows one still
+       frame where motion is reduced, and a gradient where the browser draws
+       without a GPU. -->
+  <helix-aura class="first-light" data-layer [speed]="0.4" [terminus]="0.8" variant="braid"></helix-aura>
   <div class="hero">
-    <helix-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-tag emphasis="subtle" tone="primary">Starter</helix-tag>
+    <helix-text as="h1" variant="display">Helix design system</helix-text>
+    <helix-text as="p" class="lede" variant="body">
+      Web components in your brand's colors, drawn from one set of tokens.
     </helix-text>
     <div class="actions">
       <a data-button="solid" data-button-tone="primary" href="#/overview">See the data view</a>
@@ -13,10 +16,10 @@
     </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">
+  <!-- **The library at work, on the first screen.** The figures are the roster
+       the data view draws, read from the same module, so the panel is the app
+       itself, on glass over the light. -->
+  <helix-card class="specimen" material="glass" separation="outlined">
     <helix-text as="h2" slot="header" variant="title">The roster, in three figures</helix-text>
     <helix-stat-group divided>
       <helix-stat>
@@ -38,75 +41,37 @@
 
 <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.ts</helix-code> registers all of
-        them, and a subpath like <helix-code>&#64;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">
+  <!-- **Each tile is a link, which is what `data-card` is for.** The base layer
+       draws the ring, moves the card's border to the brand on hover, and leaves
+       focus alone. Nothing inside may be interactive, since a link inside a link
+       is neither valid nor reachable. -->
+  <div class="features">
+    <a class="feature" data-card [href]="docs.elements">
       <helix-card separation="outlined">
-        <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>
+        <span class="feature-mark"><helix-icon name="cube"></helix-icon></span>
+        <helix-text as="h3" variant="title">Custom elements</helix-text>
         <helix-text as="p" emphasis="muted" variant="body">
-          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.
+          One import in <helix-code>src/main.ts</helix-code> registers every tag.
         </helix-text>
       </helix-card>
     </a>
-
-    <a data-card href="#/join">
+    <a class="feature" data-card [href]="docs.tokens">
       <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>
+        <span class="feature-mark"><helix-icon name="palette"></helix-icon></span>
+        <helix-text as="h3" variant="title">One set of tokens</helix-text>
         <helix-text as="p" emphasis="muted" variant="body">
-          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.
+          Every color, size, and space, in light and dark.
         </helix-text>
       </helix-card>
     </a>
-  </helix-grid>
+    <a class="feature" data-card [href]="docs.parts">
+      <helix-card separation="outlined">
+        <span class="feature-mark"><helix-icon name="sliders-horizontal"></helix-icon></span>
+        <helix-text as="h3" variant="title">Parts to style</helix-text>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Reach inside a component with <helix-code>::part()</helix-code>.
+        </helix-text>
+      </helix-card>
+    </a>
+  </div>
 </section>

package/templates/angular/src/app/landing.ts

@@ -8,8 +8,6 @@ import { DOCS } from './docs'
  * 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

package/templates/angular/src/app/overview.html

@@ -42,8 +42,8 @@
 
   <!-- 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
+    Filtering, column reordering, resizing, virtualized rows, and a server mode for large results
+    are on
     <a data-link [href]="docs.table">the component's own page</a>.
   </helix-text>
 </section>

package/templates/angular/src/app/pathname.ts

@@ -10,7 +10,7 @@ import { Injectable, signal } from '@angular/core'
    the same document, and wherever you deploy has to be told to. A hash asks
    nothing of it. 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 `/`. */
+/** The current path, read from the hash, so the first page is `/`. */
 const read = (): string => window.location.hash.slice(1) || '/'
 
 /** The current path, kept current as the hash changes. */

package/templates/angular/src/app/signup-form.html

@@ -14,8 +14,8 @@
     <helix-input autocomplete="name" label="Name" name="name" required></helix-input>
 
     <!-- Validation is the platform's: `type` and `required` are set on the
-         real input inside, and its own message shows once the reader has
-         touched the field. Set `feedback` to say it in your own words. -->
+         real input inside, and its own message shows once the field has been
+         touched. Set `feedback` to say it in your own words. -->
     <helix-input
       hint="Where we send the welcome note."
       label="Email"
@@ -53,18 +53,17 @@
          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.
+      The form posts nothing. Submit it, and a message shows exactly what a server would receive.
     </helix-callout>
-    <helix-text as="h2" variant="title">What this is showing</helix-text>
+    <helix-text as="h2" variant="title">What the form shows</helix-text>
     <helix-text as="p" emphasis="muted" variant="body">
-      Every control is a form-associated custom element, so the submit reads them 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.
+      Every control is a form-associated custom element, so the submit reads them all with
+      <helix-code>new FormData(form)</helix-code>. Reset the form and they all go back,
+      the way an <helix-code>input</helix-code> does.
     </helix-text>
     <helix-text as="p" emphasis="muted" variant="body">
-      Leave the email wrong and the 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.
+      Leave the email wrong and the browser shows its own message, in your language. Handle is the
+      controlled field: the page refuses each change and writes back a cleaned value.
     </helix-text>
     <a data-link [href]="docs.forms">Forms</a>
   </aside>

package/templates/angular/src/app/site-footer.html

@@ -1,6 +1,6 @@
 <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.
+    Every component here has a page, with its API, its parts, and its examples.
   </helix-text>
   <div class="footer-links">
     <a data-link="subtle" [href]="docs.gallery">Components</a>

package/templates/angular/src/app/site-header.ts

@@ -31,8 +31,7 @@ const MARKS: Record<Mode, string> = { dark: 'moon', light: 'sun', system: 'monit
 export class SiteHeader {
   protected readonly path = inject(Pathname).current
   protected readonly marks = MARKS
-  /* `system` is the resting state, so the control draws the same glyph before
-     and after the reader first touches it. */
+  /* `system` is the resting state, the mode the page follows until the control is pressed. */
   protected readonly mode = signal<Mode>('system')
 
   /**
@@ -44,7 +43,7 @@ export class SiteHeader {
    * on a panel for a light preview inside a dark page.
    *
    * `system` removes the attribute. Writing out whichever mode is current would
-   * freeze the page there the moment the reader's machine changed.
+   * hold the page there when the system's own setting changed.
    */
   protected cycle(): void {
     const next = MODES[(MODES.indexOf(this.mode()) + 1) % MODES.length] ?? 'system'