@fusion.dev/helix-templates 0.137.0 → 0.139.0

package/README.md

@@ -16,13 +16,25 @@ written against.
 |---|---|
 | `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. |
+| `vue-vite` | Vue and TypeScript on Vite. |
+| `angular` | Angular and TypeScript on the Angular CLI. |
+| `svelte-vite` | Svelte and TypeScript on Vite. |
+| `solid-vite` | Solid and TypeScript on Vite. |
 
-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.
+Every template lays 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;
+- a form whose controls a `<form>` reads with `FormData`, because they are real
+  form participants.
+
+What differs between them is what each framework requires. `bun run
+smoke:scaffold` builds every template and holds what each renders to React on
+Vite's, in markup and in pictures, so a template that drifts fails CI.
+
+Each one starts Helix diagnostics in development, checked against the lint data
+of the Helix it installed, and a production build leaves it out.
 
 **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

@@ -11,6 +11,30 @@ export const templates = [
         named: ['app/layout.tsx', 'app/site-header.tsx', 'package.json'],
         title: 'React (Next.js)',
     },
+    {
+        description: 'Vue and TypeScript on Vite.',
+        id: 'vue-vite',
+        named: ['index.html', 'package.json', 'src/SiteHeader.vue'],
+        title: 'Vue (Vite)',
+    },
+    {
+        description: 'Angular and TypeScript on the Angular CLI.',
+        id: 'angular',
+        named: ['angular.json', 'package.json', 'src/app/site-header.html', 'src/index.html'],
+        title: 'Angular',
+    },
+    {
+        description: 'Svelte and TypeScript on Vite.',
+        id: 'svelte-vite',
+        named: ['index.html', 'package.json', 'src/SiteHeader.svelte'],
+        title: 'Svelte (Vite)',
+    },
+    {
+        description: 'Solid and TypeScript on Vite.',
+        id: 'solid-vite',
+        named: ['index.html', 'package.json', 'src/site-header.tsx'],
+        title: 'Solid (Vite)',
+    },
 ];
 export const PROJECT_NAME = '__PROJECT_NAME__';
 export const HELIX_VERSION = '__HELIX_VERSION__';

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

package/templates/angular/angular.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "newProjectRoot": "projects",
+  "projects": {
+    "__PROJECT_NAME__": {
+      "projectType": "application",
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:application",
+          "options": {
+            "browser": "src/main.ts",
+            "outputPath": "dist",
+            "styles": [
+              "@fusion.dev/helix-styles/helix.css",
+              "src/app.css"
+            ],
+            "tsConfig": "tsconfig.app.json"
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "maximumError": "5MB",
+                  "maximumWarning": "2MB",
+                  "type": "initial"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "extractLicenses": false,
+              "optimization": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular/build:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "__PROJECT_NAME__:build:production"
+            },
+            "development": {
+              "buildTarget": "__PROJECT_NAME__:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        }
+      }
+    }
+  }
+}

package/templates/angular/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "ng build",
+    "dev": "ng serve",
+    "ng": "ng",
+    "start": "ng serve"
+  },
+  "dependencies": {
+    "@angular/common": "^22.2.1",
+    "@angular/compiler": "^22.2.1",
+    "@angular/core": "^22.2.1",
+    "@angular/platform-browser": "^22.2.1",
+    "@fusion.dev/helix": "^__HELIX_VERSION__",
+    "@fusion.dev/helix-styles": "^__HELIX_VERSION__",
+    "rxjs": "~7.8.0",
+    "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "@angular/build": "^22.2.1",
+    "@angular/cli": "^22.2.1",
+    "@angular/compiler-cli": "^22.2.1",
+    "@fusion.dev/helix-diagnostics": "^__HELIX_VERSION__",
+    "typescript": "~6.0.3"
+  }
+}

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

@@ -0,0 +1,8 @@
+import { type ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core'
+
+/* No zone.js, which Angular no longer needs: a signal that changes is what
+   updates a view, so the Helix elements' own events and timers start no
+   change detection of their own. */
+export const appConfig: ApplicationConfig = {
+  providers: [provideBrowserGlobalErrorListeners()],
+}

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

@@ -0,0 +1,19 @@
+<!-- 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 class="shell">
+  <app-site-header></app-site-header>
+  <main class="page">
+    @switch (path()) {
+      @case ('/overview') {
+        <div app-overview></div>
+      }
+      @case ('/join') {
+        <div app-signup-form></div>
+      }
+      @default {
+        <div app-landing></div>
+      }
+    }
+  </main>
+  <footer app-site-footer></footer>
+</div>

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

@@ -0,0 +1,29 @@
+import { Component, inject } from '@angular/core'
+import { Landing } from './landing'
+import { Overview } from './overview'
+import { Pathname } from './pathname'
+import { SignupForm } from './signup-form'
+import { SiteFooter } from './site-footer'
+import { SiteHeader } from './site-header'
+
+/**
+ * The shell, and the switch between the three pages.
+ *
+ * Helix components are custom elements, so you write the tags directly. There
+ * is no wrapper package and nothing to import per component: `src/main.ts`
+ * registers them once, and every tag in the app is real from then on.
+ *
+ * **A page and the footer are each a component on the element it draws**,
+ * selected by an attribute: `footer[app-site-footer]`, and a `div` for each
+ * page. A tag of their own would put an element between the shell and what
+ * they draw, which the shell's column and `app.css` would then have to know
+ * about. The header is the exception, and `site-header.ts` says why.
+ */
+@Component({
+  imports: [Landing, Overview, SignupForm, SiteFooter, SiteHeader],
+  selector: 'app-root',
+  templateUrl: './app.html',
+})
+export class App {
+  protected readonly path = inject(Pathname).current
+}

package/templates/angular/src/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/angular/src/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 = {
+  /** Angular specifically: the schema, property bindings, and events. */
+  angular: 'https://fusion.dev/helix/docs/angular',
+  /** 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',
+  /** 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/angular/src/app/landing.html

@@ -0,0 +1,112 @@
+<header class="first-screen">
+  <div class="hero">
+    <helix-text emphasis="muted" variant="label">Helix starter</helix-text>
+    <helix-text as="h1">Every tag on this page is Helix</helix-text>
+    <helix-text as="p" class="lede" emphasis="muted" variant="body">
+      Nothing here is a wrapper: the tags are the library's own elements, and every color,
+      size and space inside them comes from one set of tokens. Three routes are laid down, and
+      all of them are yours.
+    </helix-text>
+    <div class="actions">
+      <a data-button="solid" data-button-tone="primary" href="#/overview">See the data view</a>
+      <a data-button href="#/join">Open the form</a>
+    </div>
+  </div>
+
+  <!-- The figures are the roster the data view draws, read from the same
+       module, so the panel is the app at work. `helix-stat` sets the number
+       on the display face at a size the type scale does not reach. -->
+  <helix-card class="specimen" separation="outlined">
+    <helix-text as="h2" slot="header" variant="title">The roster, in three figures</helix-text>
+    <helix-stat-group divided>
+      <helix-stat>
+        {{ roster.people }}
+        <span slot="label">People</span>
+      </helix-stat>
+      <helix-stat>
+        {{ roster.teams }}
+        <span slot="label">Teams</span>
+      </helix-stat>
+      <helix-stat>
+        {{ figure.format(roster.reviews) }}
+        <span slot="label">Reviews</span>
+      </helix-stat>
+    </helix-stat-group>
+    <a data-link href="#/overview" slot="footer">Open the data view</a>
+  </helix-card>
+</header>
+
+<section class="section">
+  <helix-text as="h2" variant="subheading">What you have</helix-text>
+  <!-- Three paragraphs about one installed thing, so they take a rule each
+       and no box. `app.css` says why at more length. -->
+  <div class="facts">
+    <article class="fact">
+      <helix-text as="h3" variant="title">Elements, not wrappers</helix-text>
+      <helix-text as="p" emphasis="muted" variant="body">
+        They are custom elements, so you write the tags and there is no per-component import
+        to keep in step. One line in <helix-code>src/main.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">
+      <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>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Twelve people from a local module, sorted, paged and selected with nothing wired up.
+          The columns are markup you can read and the rows are one property, which is what
+          keeps the same component working at ten thousand.
+        </helix-text>
+      </helix-card>
+    </a>
+
+    <a data-card href="#/join">
+      <helix-card separation="outlined">
+        <helix-flex align-items="baseline" gap="sm" justify-content="between" slot="header">
+          <helix-text as="h3" variant="title">The form</helix-text>
+          <helix-text emphasis="subtle" variant="code">/join</helix-text>
+        </helix-flex>
+        <helix-text as="p" emphasis="muted" variant="body">
+          Five controls a <helix-code>&lt;form&gt;</helix-code> reads with
+          <helix-code>FormData</helix-code>, because every one of them is a real form
+          participant. The email field's complaint is the browser's own.
+        </helix-text>
+      </helix-card>
+    </a>
+  </helix-grid>
+</section>

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

@@ -0,0 +1,31 @@
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
+import { roster } from './data'
+import { DOCS } from './docs'
+
+/**
+ * The first screen, and the only page here about the starter itself.
+ *
+ * Delete it once you know your way around: nothing else imports it, and the
+ * route it answers becomes yours.
+ *
+ * **The heading says what this is, and the project's name stays in the bar.**
+ *
+ * **The calls to action are anchors.** A button that navigates is a link
+ * dressed as a button, and the two are different things to a keyboard and to
+ * a screen reader. The base stylesheet styles an anchor that asks with
+ * `data-button`, so a link can look like one and stay a link.
+ */
+@Component({
+  host: { class: 'stack' },
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  selector: 'div[app-landing]',
+  templateUrl: './landing.html',
+})
+export class Landing {
+  protected readonly docs = DOCS
+  protected readonly roster = roster
+  /* **A locale named, so the number reads the same everywhere.**
+     `toLocaleString()` with no argument reads the machine's locale, so the same
+     number is grouped two ways on two machines. */
+  protected readonly figure = new Intl.NumberFormat('en-US')
+}

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

@@ -0,0 +1,49 @@
+<header class="hero">
+  <helix-text emphasis="muted" variant="label">Data view</helix-text>
+  <helix-text as="h1" variant="heading">Roster</helix-text>
+  <helix-text as="p" class="lede" emphasis="muted" variant="body">
+    Twelve people from a local module. Sort a column, turn a page, or tick a row and watch the
+    rule in <helix-code>src/app.css</helix-code> paint it.
+  </helix-text>
+</header>
+
+<section class="section">
+  <helix-data-table
+    default-sort="name:asc"
+    label="Roster"
+    page-size="6"
+    row-key="id"
+    [rows]="members"
+    selectable
+  >
+    <!-- **Every column declares what it may give up.** A floor and a share:
+         the floor is what the words need, and the share is how the slack is
+         divided. At 390 the four columns and the checkboxes fit the box, and
+         below 376 the table scrolls its own box. -->
+    <helix-table-column field="name" sortable width="minmax(5.5rem, 1.6fr)">
+      Name
+    </helix-table-column>
+    <helix-table-column field="team" sortable width="minmax(4.5rem, 1fr)">
+      Team
+    </helix-table-column>
+    <helix-table-column field="role" width="minmax(4.5rem, 1fr)">Role</helix-table-column>
+    <!-- `end` lines the digits up under each other. `max-content`, since a
+         column of numerals has one right width. -->
+    <helix-table-column field="reviews" sortable text-align="end" width="max-content">
+      Reviews
+    </helix-table-column>
+
+    <!-- The footer is a row across the table: anything you slot goes at the
+         start, and the table's own pagination sits at the end. -->
+    <helix-text emphasis="subtle" slot="footer" variant="caption">
+      {{ members.length }} people
+    </helix-text>
+  </helix-data-table>
+
+  <!-- A footnote to the table, so it takes the section's gap. -->
+  <helix-text as="p" emphasis="muted" variant="caption">
+    Filtering, column reordering, resizing, virtualized rows and a server mode that asks you
+    for a page are all on
+    <a data-link [href]="docs.table">the component's own page</a>.
+  </helix-text>
+</section>

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

@@ -0,0 +1,25 @@
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'
+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]` hands over the whole result
+ * at once, since a table of ten thousand rows cannot be written out as
+ * elements. The table sorts, pages, and selects out of that array on its own.
+ *
+ * **Selection is keyed on `row-key`, so it survives a sort and a page.**
+ * `app.css` paints the chosen row through the parts the table names for it.
+ */
+@Component({
+  host: { class: 'stack' },
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  selector: 'div[app-overview]',
+  templateUrl: './overview.html',
+})
+export class Overview {
+  protected readonly docs = DOCS
+  protected readonly members = members
+}

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

@@ -0,0 +1,24 @@
+import { Injectable, signal } from '@angular/core'
+
+/* **The whole router, which is a hash and a listener.**
+
+   Three pages need `location.hash` and one event. Swap this file for the
+   Angular router when you want lazy routes or guards: `withHashLocation()`
+   keeps these addresses.
+
+   A hash, because the History API wants a server that answers every path with
+   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 `/`. */
+const read = (): string => window.location.hash.slice(1) || '/'
+
+/** The current path, kept current as the hash changes. */
+@Injectable({ providedIn: 'root' })
+export class Pathname {
+  readonly current = signal(read())
+
+  constructor() {
+    window.addEventListener('hashchange', () => this.current.set(read()))
+  }
+}