@fusion.dev/helix-templates 0.138.0 → 0.140.0

package/templates/solid-vite/src/landing.tsx

@@ -0,0 +1,130 @@
+import { roster } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/**
+ * **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.
+ */
+const figure = new Intl.NumberFormat('en-US')
+
+/**
+ * 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 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.
+ */
+export function Landing() {
+  return (
+    <div class="stack">
+      <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" />
+        <div class="hero">
+          <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>
+            <a data-button href="#/join">
+              Open the form
+            </a>
+          </div>
+        </div>
+
+        {/* **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>
+              {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>
+        {/* **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">
+              <span class="feature-mark">
+                <helix-icon name="cube" />
+              </span>
+              <helix-text as="h3" variant="title">
+                Custom elements
+              </helix-text>
+              <helix-text as="p" emphasis="muted" variant="body">
+                One import in <helix-code>src/main.tsx</helix-code> registers every tag.
+              </helix-text>
+            </helix-card>
+          </a>
+          <a class="feature" data-card href={DOCS.tokens}>
+            <helix-card separation="outlined">
+              <span class="feature-mark">
+                <helix-icon name="palette" />
+              </span>
+              <helix-text as="h3" variant="title">
+                One set of tokens
+              </helix-text>
+              <helix-text as="p" emphasis="muted" variant="body">
+                Every color, size, and space, in light and dark.
+              </helix-text>
+            </helix-card>
+          </a>
+          <a class="feature" data-card href={DOCS.parts}>
+            <helix-card separation="outlined">
+              <span class="feature-mark">
+                <helix-icon name="sliders-horizontal" />
+              </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>
+    </div>
+  )
+}

package/templates/solid-vite/src/main.tsx

@@ -0,0 +1,23 @@
+import { render } from 'solid-js/web'
+
+/* 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.tsx'
+
+/* **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')
+}
+
+render(() => <App />, document.querySelector('#root') as HTMLElement)

package/templates/solid-vite/src/overview.tsx

@@ -0,0 +1,78 @@
+import { members } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/**
+ * 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, 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.
+ */
+export function Overview() {
+  return (
+    <div class="stack">
+      <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 for large
+          results are on{' '}
+          <a data-link href={DOCS.table}>
+            the component's own page
+          </a>
+          .
+        </helix-text>
+      </section>
+    </div>
+  )
+}

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

@@ -0,0 +1,22 @@
+import { type Accessor, createSignal } from 'solid-js'
+
+/* **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 Solid Router when you want nested routes or
+   preloading: its `HashRouter` keeps these addresses.
+
+   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) || '/'
+
+const [path, setPath] = createSignal(read())
+
+window.addEventListener('hashchange', () => setPath(read()))
+
+/** The current path, kept current as the hash changes. */
+export const pathname: Accessor<string> = path

package/templates/solid-vite/src/signup-form.tsx

@@ -0,0 +1,151 @@
+import { createSignal, For, type JSX } from 'solid-js'
+import { teams } from './data.ts'
+import { DOCS } from './docs.ts'
+
+/** 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>`.
+ * The submit 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`.
+ */
+export function SignupForm() {
+  const [handle, setHandle] = createSignal('')
+  const [messages, setMessages] = createSignal<readonly Message[]>([])
+
+  const join: JSX.EventHandler<HTMLFormElement, SubmitEvent> = (event) => {
+    /* The page takes the submit, 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 class="stack">
+      <header class="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" class="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.
+          At 390 the two stack, and the notes read as a postscript. */}
+      <div class="split">
+      <form class="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 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"
+          name="email"
+          required
+          type="email"
+        />
+
+        {/* **A controlled value, which is the one habit to unlearn.** `on:` binds
+            the event by its own name. 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()`, then setting the value you want. Leaving
+            `handle` as it was does not refuse anything. */}
+        <helix-input
+          hint="Lowercase and hyphens, whatever you type."
+          label="Handle"
+          name="handle"
+          on:helix-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>
+          <For each={teams}>{(team) => <helix-option value={team}>{team}</helix-option>}</For>
+        </helix-select>
+
+        {/* A switch is a thing happening now, 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 class="notes">
+          {/* The one fact you need before typing your name into a page you have
+              had for five minutes, so it is a callout. `tone` is the meaning,
+              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">
+            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 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 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 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>
+      </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 often never announced. A
+          dismissed message asks to go through `helix-dismiss`. */}
+      <helix-toast>
+        <For each={messages()}>
+          {(message) => (
+            <helix-toast-item
+              dismissible
+              duration={8000}
+              on:helix-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>
+          )}
+        </For>
+      </helix-toast>
+    </div>
+  )
+}

package/templates/solid-vite/src/site-footer.tsx

@@ -0,0 +1,34 @@
+import { DOCS } from './docs.ts'
+
+/**
+ * The bar's counterpart, on every route.
+ *
+ * **It puts a floor under the content.** The overview is a heading, a table,
+ * and a caption, which on a tall window left the bottom third of the screen
+ * empty. The footer is also where the links you want once belong.
+ *
+ * `data-link="subtle"` reads as body text until it is hovered, which suits a
+ * row of links under a rule.
+ */
+export function SiteFooter() {
+  return (
+    <footer class="site-footer">
+      <div class="footer-row">
+        <helix-text as="p" emphasis="subtle" variant="caption">
+          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>
+          <a data-link="subtle" href={DOCS.elements}>
+            Documentation
+          </a>
+          <a data-link="subtle" href={DOCS.solid}>
+            Solid
+          </a>
+        </div>
+      </div>
+    </footer>
+  )
+}

package/templates/solid-vite/src/site-header.tsx

@@ -0,0 +1,76 @@
+import { createSignal } from 'solid-js'
+import { pathname } from './routes.ts'
+
+/** What the page can follow, in the order the control cycles them. */
+const MODES = ['system', 'light', 'dark'] as const
+
+type Mode = (typeof MODES)[number]
+
+/** The glyph each mode is announced and drawn with. */
+const MARKS: Record<Mode, string> = { dark: 'moon', light: 'sun', system: 'monitor' }
+
+/**
+ * The bar across the top: the wordmark, the destinations, and the color mode.
+ */
+export function SiteHeader() {
+  /* `system` is the resting state, the mode the page follows until the control is pressed. */
+  const [mode, setMode] = createSignal<Mode>('system')
+
+  /**
+   * One attribute, two modes, and no second stylesheet.
+   *
+   * Every Helix token is written once as a `light-dark()` pair, so
+   * `color-scheme` decides which half resolves. `data-color-mode` sets it, and
+   * since `color-scheme` inherits, the attribute works on any element: put it
+   * on a panel for a light preview inside a dark page.
+   *
+   * `system` removes the attribute. Writing out whichever mode is current would
+   * hold the page there when the system's own setting changed.
+   */
+  const cycle = () => {
+    const next = MODES[(MODES.indexOf(mode()) + 1) % MODES.length] ?? 'system'
+    setMode(next)
+    if (next === 'system') {
+      delete document.documentElement.dataset.colorMode
+      return
+    }
+    document.documentElement.dataset.colorMode = next
+  }
+
+  return (
+    <helix-app-header material="glass" sticky>
+      {/* The wordmark is the way back to the first page, so there is no third
+          destination in the bar saying the same thing. It is also the only name
+          of the project on the screen. The mark is a placeholder for your own,
+          drawn in `--helix-color-brand-mark`, the token for the brand as a
+          graphic. */}
+      <a class="wordmark" data-link="quiet" href="#/" slot="start">
+        <helix-icon name="cube" />
+        <helix-text variant="body-strong">__PROJECT_NAME__</helix-text>
+      </a>
+
+      {/* The links are yours. Navigation owns the marker that travels between
+          them and renders no anchors of its own. The base layer styles them,
+          `aria-current="page"` included. */}
+      <helix-navigation label="Pages">
+        <a aria-current={pathname() === '/overview' ? 'page' : undefined} href="#/overview">
+          Overview
+        </a>
+        <a aria-current={pathname() === '/join' ? 'page' : undefined} href="#/join">
+          Join
+        </a>
+      </helix-navigation>
+
+      {/* An icon with no words has no accessible name until it is given one,
+          which is why this is its own element. */}
+      <helix-icon-button
+        label={`Color mode: ${mode()}`}
+        onClick={cycle}
+        slot="end"
+        title={`Color mode: ${mode()}`}
+      >
+        <helix-icon name={MARKS[mode()]} />
+      </helix-icon-button>
+    </helix-app-header>
+  )
+}

package/templates/solid-vite/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2023"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2023",
+    "types": [
+      "vite/client"
+    ],
+    "verbatimModuleSyntax": true
+  },
+  "include": [
+    "src",
+    "helix-solid.d.ts"
+  ]
+}

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

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import solid from 'vite-plugin-solid'
+
+/* Solid needs no setting for custom elements: it sets a property on one by
+   default, `attr:` forces an attribute, and `on:` binds an event by its own
+   name. */
+export default defineConfig({ plugins: [solid()] })

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

@@ -0,0 +1,9 @@
+/**
+ * Types for the Helix custom elements in Svelte components.
+ *
+ * Generated from the same manifest the API pages read, so a wrong prop or a
+ * wrong event detail is an error in `svelte-check`. The import augments
+ * `SvelteHTMLElements` with the JSX typings, which already describe a handler
+ * bound as `onhelix-before-change={…}`.
+ */
+import '@fusion.dev/helix/svelte'

package/templates/svelte-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/svelte-vite/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "svelte-check && vite build",
+    "dev": "vite",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fusion.dev/helix": "^__HELIX_VERSION__",
+    "@fusion.dev/helix-styles": "^__HELIX_VERSION__"
+  },
+  "devDependencies": {
+    "@fusion.dev/helix-diagnostics": "^__HELIX_VERSION__",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "svelte": "^5.57.1",
+    "svelte-check": "^4.7.6",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.0"
+  }
+}

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

@@ -0,0 +1,35 @@
+<!--
+  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.
+-->
+<script lang="ts">
+  import Landing from './Landing.svelte'
+  import Overview from './Overview.svelte'
+  import { route } from './routes.svelte.ts'
+  import SignupForm from './SignupForm.svelte'
+  import SiteFooter from './SiteFooter.svelte'
+  import SiteHeader from './SiteHeader.svelte'
+
+  /** The page for each path, in the order the bar offers them. */
+  const PAGES = {
+    '/': Landing,
+    '/join': SignupForm,
+    '/overview': Overview,
+  }
+
+  const Page = $derived(PAGES[route.path as keyof typeof PAGES] ?? Landing)
+</script>
+
+<div class="shell">
+  <SiteHeader />
+  <main class="page">
+    <Page />
+  </main>
+  <SiteFooter />
+</div>