@fusion.dev/helix-templates 0.138.0 → 0.140.0

package/templates/svelte-vite/src/app.css

@@ -0,0 +1,355 @@
+/*
+ * The page around the components.
+ *
+ * Helix draws the inside of each component, so an app stylesheet holds the
+ * measure, the rhythm between blocks, and the few decisions a component leaves
+ * open. Everything below is a Helix token or a documented hook, so a theme
+ * changes it, and both color modes follow from one copy.
+ *
+ * **Color appears in two places, and both are named.** The wordmark takes
+ * `--helix-color-brand-mark`, the token for the brand as a graphic, and a
+ * chosen row takes `--helix-color-primary-subtle` through the parts the table
+ * publishes. Everywhere else the page is ink on the background, and the
+ * components carry their own color.
+ */
+
+/*
+ * **The shell: a column the height of the window, with the footer at its end.**
+ * The overview is a header, a table, and a caption, which on a 1280 by 900
+ * window left about four hundred empty pixels under it. The column puts a floor
+ * under every route.
+ *
+ * **A flex column, because the bar is sticky.** A grid item's containing block
+ * is its own grid area, one row as tall as the bar, so a sticky header in a
+ * grid row has nowhere to stick. A flex item's containing block is the flex
+ * container, which here is the whole document.
+ */
+.shell {
+  display: flex;
+  flex-direction: column;
+  min-block-size: 100dvh;
+}
+
+/*
+ * **56rem, the width the widest block reads well at.** 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 stretched table. The
+ * bar and the footer are centered in the same width, so the wordmark sits over
+ * the first column of the page.
+ *
+ * `flex-grow` gives the spare height to the page, and the footer keeps its own.
+ */
+.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, both to match the page. The bar centers its row in the
+ * page's measure, so the wordmark sits over the first column. And the bar draws
+ * no line under itself by default, since a header over a page with its own
+ * surface needs none: this page has no such surface, so it sets one. The line
+ * is a token, 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, the one graphic on the page and the
+   reason `--helix-color-brand-mark` exists. WCAG asks 3:1 of a graphic and 4.5:1
+   of text, so a mark can sit closer to a theme's brand color 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 sets its own.
+ *
+ * **`minmax(0, 1fr)` for every column, the guard every grid here needs.** An
+ * implicit track is `auto`, and an `auto` track's minimum is its content's
+ * min-content size, so a child that scrolls itself widens the track 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, so the whole page scrolled sideways. A
+ * minimum of zero leaves the overflow to the table, which scrolls its own box.
+ */
+.stack,
+.section,
+.hero,
+.first-screen,
+.features,
+.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, and the `md` a section puts between its
+   heading and its block. */
+.stack {
+  display: grid;
+  gap: var(--helix-space-3xl);
+}
+
+/*
+ * **The first screen: one lit panel, with what the starter is on the left and
+ * the library at work on the right.** Below 60rem two readable columns do not
+ * fit, so they become one, and the glass card follows the words.
+ *
+ * `isolation` makes the panel its own stacking context, so the light behind it
+ * sits under the content and above the page, and `overflow: clip` keeps the
+ * light inside the rounded corners.
+ */
+.first-screen {
+  align-items: center;
+  border: var(--helix-border-thin) solid var(--helix-color-border);
+  border-radius: var(--helix-radii-lg);
+  display: grid;
+  gap: var(--helix-space-2xl);
+  isolation: isolate;
+  overflow: clip;
+  padding: var(--helix-space-3xl) var(--helix-space-2xl);
+  position: relative;
+}
+
+@media (width >= 60rem) {
+  .first-screen {
+    grid-template-columns: minmax(0, 1fr) minmax(0, 18rem);
+  }
+}
+
+/* The light, under everything in the panel and out of the way of the pointer,
+   and faded out behind the words so they keep their contrast: it is at full
+   strength only behind the card, which is below the words in one column and
+   beside them in two. */
+.first-light {
+  block-size: auto;
+  inset: 0;
+  mask-image: linear-gradient(to bottom, transparent 40%, black 80%);
+  pointer-events: none;
+  position: absolute;
+  z-index: var(--helix-layer-beneath);
+}
+
+@media (width >= 60rem) {
+  .first-light {
+    mask-image: linear-gradient(to right, transparent 35%, black 70%);
+  }
+}
+
+/* A heading and the lines around it are one block, with a smaller gap than the
+   one between blocks. Every route opens with one. */
+.hero {
+  display: grid;
+  gap: var(--helix-space-xs);
+  justify-items: start;
+}
+
+/* The first screen's heading takes more room around it than a route's, and
+   its lede a step more size, wrapped to even lines. */
+.first-screen .hero {
+  gap: var(--helix-space-md);
+}
+
+.first-screen .lede {
+  font-size: var(--helix-text-lg);
+  text-wrap: balance;
+}
+
+/* **A measure for the lede, narrower than the page's.** A line of prose across
+   56rem is around 110 characters, and the readable range tops out near 75. The
+   heading above it keeps the page's measure, since a heading is scanned. */
+.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 at work**, so all it needs from here is room. Two
+ * documented hooks: the figures come down a step from the display size, which
+ * suits one figure on its own and is too loud for three in an 18rem column, and
+ * the gap around the rule between them comes in from `2xl`, which `divided`
+ * doubles, leaving no room for a number.
+ */
+.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 tiles, side by side where there is room for three. */
+.features {
+  display: grid;
+  gap: var(--helix-space-lg);
+}
+
+@media (width >= 48rem) {
+  .features {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+}
+
+/* The card fills the link that wraps it, so the row of tiles ends level: the
+   anchor is the grid item, which stretches, and the card takes its full height. */
+[data-card] > helix-card {
+  block-size: 100%;
+}
+
+/* Each tile's icon, on a tint of the brand. */
+.feature-mark {
+  --icon-size: 1.25rem;
+  background-color: var(--helix-color-primary-subtle);
+  border-radius: var(--helix-radii-md);
+  color: var(--helix-color-primary);
+  display: inline-flex;
+  inline-size: fit-content;
+  padding: var(--helix-space-xs);
+}
+
+/* A form is read straight down, and a field wider than about 28rem is hard to
+   scan, 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 alone
+ * on a 1280 window fills a third of the page and leaves two thirds empty: the
+ * form has a right width, and the page keeps its own. Narrow, the two stack,
+ * and the notes read as a postscript, 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, which gives every route an end.** The rule runs
+ * the width of the window while its contents keep the page's measure, as a
+ * footer under a centered page does. The shell above 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 first.** 24 pixels either side of a 390 window
+ * spend 48 of 390 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 you scrolled the table sideways.
+ */
+@media (width < 40rem) {
+  .first-screen {
+    padding: var(--helix-space-2xl) var(--helix-space-lg);
+  }
+
+  .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
+ * tints a chosen row at the strength `Tag` rests at, and this page wants a
+ * ticked row easy to find from across the screen, a step past any token.
+ * `::part` reaches the boxes the component drew, with no fork, and a rule
+ * written out here beats the component's own, however specific that one is.
+ *
+ * **Two parts, because a row has no box.** The row is `display: contents`, so
+ * one grid can align every column across every row, and the cells are what a
+ * selection is 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`, because `primary-surface` is the solid accent a
+ * button stands on, made for white text, so a row painted with it would put 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/svelte-vite/src/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 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, 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.
+   *
+   * 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
+  /**
+   * The name a row is found by.
+   */
+  readonly name: string
+  /**
+   * 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 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 from the rows, so the panel and the table always agree.
+ */
+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/svelte-vite/src/diagnostics.ts

@@ -0,0 +1,24 @@
+/**
+ * Helix diagnostics, which `main.ts` loads in development only.
+ *
+ * It finds the Helix mistakes that are valid CSS and therefore silent, such as
+ * a `::part()` naming a part nothing publishes, and an attribute value outside
+ * the set a component takes. Each finding prints once in DevTools, and a badge
+ * in the corner of the page lists them while there are any.
+ *
+ * **Checked against the Helix you installed**, from the lint data it ships, so
+ * nothing is loaded from the network.
+ *
+ * To print the findings in your terminal as well, run `npx helix diagnostics`
+ * from `@fusion.dev/helix-cli` beside the dev server, and add
+ * `sinks: { relay: true }` below.
+ */
+import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+import lint from '@fusion.dev/helix/lint.json'
+
+initDiagnostics({
+  environment: 'development',
+  /* The route is in the hash, so each page's findings are kept apart. */
+  page: () => window.location.hash.slice(1) || '/',
+  tiers: [{ lint }],
+})

package/templates/svelte-vite/src/docs.ts

@@ -0,0 +1,29 @@
+/**
+ * The documentation the starter links to.
+ *
+ * **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 October 4, 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 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',
+  /** Svelte specifically: the typings, props, and events. */
+  svelte: 'https://fusion.dev/helix/docs/svelte',
+  /** 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/svelte-vite/src/main.ts

@@ -0,0 +1,23 @@
+import { mount } from 'svelte'
+
+/* Every layer in one import: the tokens, the reset, the utility layer, and the
+   `:not(:defined)` rules that keep a tag from arriving unstyled. It reaches its
+   pieces by bare specifier, so a bundler resolves it and a `<link>` cannot. */
+import '@fusion.dev/helix-styles/helix.css'
+/* A custom element registers as a side effect of being imported, so this line
+   makes every Helix tag in the app real. Import the whole library while you are
+   finding your feet. `@fusion.dev/helix/button` and its siblings are subpath
+   exports, for when you want to 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.svelte'
+
+/* **Diagnostics in development, and none of it in a build.** `vite build`
+   replaces `import.meta.env.DEV` with `false` and drops the import with it. */
+if (import.meta.env.DEV) {
+  void import('./diagnostics.ts')
+}
+
+mount(App, { target: document.querySelector('#app') as HTMLElement })

package/templates/svelte-vite/src/routes.svelte.ts

@@ -0,0 +1,19 @@
+/* **The whole router, which is a hash and a listener.**
+
+   Three pages need `location.hash` and one event, so the starter leaves the
+   router to you. Swap this file for the router you want.
+
+   A hash, because the History API wants a server that answers every path with
+   the same document, and `vite preview` and wherever you deploy each have to be
+   told to. A hash asks nothing of either. Each link in the app is a plain
+   anchor to `#/` and a path. */
+
+/** 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. */
+export const route = $state({ path: read() })
+
+window.addEventListener('hashchange', () => {
+  route.path = read()
+})

package/templates/svelte-vite/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2023",
+    "types": [
+      "svelte",
+      "vite/client"
+    ],
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.svelte",
+    "helix-svelte.d.ts"
+  ]
+}

package/templates/svelte-vite/vite.config.ts

@@ -0,0 +1,7 @@
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { defineConfig } from 'vite'
+
+/* Svelte needs no setting for custom elements: it sets a property where the
+   element has one, an attribute otherwise, and binds `on*` with
+   `addEventListener`. */
+export default defineConfig({ plugins: [svelte()] })

package/templates/vue-vite/helix-vue.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Types for the Helix custom elements in Vue templates.
+ *
+ * Generated from the same manifest the API pages read, so a wrong prop or a
+ * wrong event detail is a compile error in `vue-tsc`. The import augments Vue's
+ * `GlobalComponents`, so every Helix tag in an SFC template is typed.
+ */
+import '@fusion.dev/helix/vue'

package/templates/vue-vite/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>__PROJECT_NAME__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/vue-vite/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vue-tsc && vite build",
+    "dev": "vite",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fusion.dev/helix": "^__HELIX_VERSION__",
+    "@fusion.dev/helix-styles": "^__HELIX_VERSION__",
+    "vue": "^3.5.43"
+  },
+  "devDependencies": {
+    "@fusion.dev/helix-diagnostics": "^__HELIX_VERSION__",
+    "@vitejs/plugin-vue": "^6.0.9",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.0",
+    "vue-tsc": "^3.3.12"
+  }
+}

package/templates/vue-vite/src/App.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import LandingPage from './LandingPage.vue'
+import OverviewPage from './OverviewPage.vue'
+import { usePathname } from './routes.ts'
+import SignupForm from './SignupForm.vue'
+import SiteFooter from './SiteFooter.vue'
+import SiteHeader from './SiteHeader.vue'
+
+/** The page for each path, in the order the bar offers them. */
+const PAGES = {
+  '/': LandingPage,
+  '/join': SignupForm,
+  '/overview': OverviewPage,
+}
+
+const path = usePathname()
+const page = computed(() => PAGES[path.value as keyof typeof PAGES] ?? LandingPage)
+</script>
+
+<!--
+  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.
+
+  The bar, the route, and the footer sit in a column the height of the window.
+  `app.css` says why the footer is worth having and why the column is flex.
+-->
+<template>
+  <div class="shell">
+    <SiteHeader />
+    <main class="page">
+      <component :is="page" />
+    </main>
+    <SiteFooter />
+  </div>
+</template>