@fusion.dev/helix-docs 0.206.0 → 0.207.0

package/content/using-the-elements.mdx

@@ -97,8 +97,14 @@ import '@fusion.dev/helix-styles/helix.css'
 base layer. If you import the layers one at a time, import `elements.css` last.
 
 `elements.css` hides each tag with `:not(:defined)` until the element upgrades.
-It uses `visibility`, so the page does not reflow. Without it, a card appears as
-unstyled text and then jumps into its card layout.
+It uses `visibility`, so a hidden element keeps the size of its unstyled
+content. The layout settles when the elements upgrade and take their own size.
+Without the file, a card appears as unstyled text and then jumps into its card
+layout.
+
+A data table that serves its first page as rows is the one element shown before
+it upgrades. `elements.css` lays out those rows as the table draws them. See
+[React](./react).
 
 We generate the file from the element sources, and it lists every tag by name.
 CSS has no selector for any custom element, and a bare `:not(:defined)` would
@@ -116,33 +122,28 @@ use a button.
 
 ## Turn off an attribute that is on by default
 
-A boolean attribute is off until you write it, with four exceptions. These are
-on until you write the string `"false"`:
-
-- `modal` on Drawer
-- `playsinline` on Video
-- `default-pinned` on Chat
-- `tab-indents` on Sandbox Source
+A boolean attribute is off until you write it, unless its default is `true`. The
+property table on each component's page shows the default. An attribute whose
+default is `true` stays on until you write the string `"false"`, such as `modal`
+on Drawer:
 
 ```html
 <helix-drawer modal="false"></helix-drawer>
 ```
 
-In JSX, `modal={false}` sets the property and does the same. Other features
-that are on by default turn off with an attribute named `no-`, such as
-`no-copy`.
+`"false"` is the only value that turns it off. An empty value, or any other
+string, leaves it on. In JSX, `modal={false}` sets the property and does the
+same. Other features that are on by default turn off with an attribute named
+`no-`, such as `no-copy`.
 
 ## Declarative shadow DOM is opt-in
 
-The site ships no declarative shadow DOM (DSD). The shadow styles load with the
-element definition. You do not need to configure anything. If you render with
-Lit SSR yourself, its declarative shadow DOM hydrates. See
-[Server rendering](./server-rendering).
-
-The site ships no DSD for three reasons:
+The elements need no declarative shadow DOM (DSD). Each element attaches its
+shadow root and loads its styles with its definition, so you do not need to
+configure anything. If you render with Lit SSR yourself, the DSD it writes
+hydrates. See [Server rendering](./server-rendering).
 
-- DSD cannot activate for nodes inserted by script.
-- React inserts a server component's output by replaying the flight payload
-  through DOM APIs, without running the component again.
-- The patch that made DSD work hooked into webpack, and Turbopack ignores that
-  hook without an error.
+DSD does not work in a React server component. React inserts a server
+component's output by replaying the flight payload through DOM APIs, without
+running the component again, and DSD does not activate for nodes that a script
+inserts.

package/content/versioning.mdx

@@ -31,13 +31,13 @@ the same version were tested together.
 
 ## The version number comes from the Git tag
 
-Every manifest in the repository has the version `0.0.0-dev`. CI writes the real
-number into each manifest seconds before packing.
+CI computes each version from the Git tags and writes it into every package
+manifest seconds before packing. Once the release is promoted, CI commits the
+same number back to `main`. The `version` in each Helix `package.json` in the
+repository is therefore the last release, and the tag is the record it copies.
 
-If you read the source, you will see `0.0.0-dev` on every package, including
-released ones. We do not commit the real number back. That would need a bot
-with push access that overrides branch protection, and `git tag` already records
-the number.
+The Rust crates stay at `0.0.0-dev`. The `helix` binary reports the version of
+the npm package it was installed with.
 
 Releases use two kinds of tag:
 
@@ -69,8 +69,15 @@ one of:
 - `stable`
 - `deprecated`
 
-Most components are experimental today, and their status says so. We will not
-change a status to make the library look more finished than it is.
+Most components are stable. These families are experimental, and their status
+says so:
+
+- the spatial charts, which draw in three dimensions
+- Log
+- Strands
+- Motion Toggle
+
+We will not change a status to make the library look more finished than it is.
 
 ## Release notes
 

package/content/visual-axes.mdx

@@ -28,7 +28,7 @@ accept a subset of an axis's values.
   tone="primary"
 >Save</helix-button>
 <helix-card separation="outlined">…</helix-card>
-<helix-megamenu material="glass">…</helix-megamenu>
+<helix-drawer material="glass">…</helix-drawer>
 ```
 
 ## Why there is no `appearance` attribute
@@ -52,9 +52,16 @@ build.
 ## When a property needs two axes
 
 **If two values can apply at the same time, they belong on two axes.**
-`Megamenu` is the example. `variant="band"` sets the layout of its panel, and
-glass is a `material`. A panel can be a band and glass at once, so the two
-values sit on two axes. A panel can also be glass and outlined at once.
+`Card` is the example. `separation` sets where its surface ends, and `material`
+sets what fills it. A card can be outlined and glass at once, so the two values
+sit on two axes:
+
+```html
+<helix-card
+  material="glass"
+  separation="outlined"
+>…</helix-card>
+```
 
 If you are adding a property and cannot decide which axis it belongs on, it is
 usually two properties.

package/content/vue.mdx

@@ -16,6 +16,23 @@ Helix tag in an SFC template has typed props and events. The generated file
 declares the augmentation under both `vue` and `@vue/runtime-core`, because
 different tools read different ones.
 
+## Report a misspelled prop
+
+`vue-tsc` checks the value of each prop a Helix tag declares. By default, it
+does not report a prop name that the tag does not declare, so a misspelled prop
+compiles. To report one, turn on `checkUnknownProps` in `tsconfig.json`:
+
+```json
+{
+  "vueCompilerOptions": {
+    "checkUnknownProps": true
+  }
+}
+```
+
+`strictTemplates` turns it on with the rest of Vue's strict template checks.
+Either option also reports a `data-*` attribute on a Helix tag.
+
 ## Mark Helix tags as custom elements
 
 Without this setting, Vue treats `<helix-button>` as a component it cannot find
@@ -70,7 +87,7 @@ work. See [State and control](./state-and-control).
 <helix-input default-value="Ada" label="Name" />
 
 <!-- Mirrored: bind the notification and let the element apply. -->
-<helix-input label="Name" @change="name = $event.target.value" />
+<helix-input label="Name" @change="name = ($event.currentTarget as HelixInput).value" />
 
 <!-- Refused: you take the decision for this one change. -->
 <helix-input
@@ -79,3 +96,13 @@ work. See [State and control](./state-and-control).
   @helix-before-change="$event.preventDefault(); name = clean($event.detail.value)"
 />
 ```
+
+For a native event such as `change`, `vue-tsc` types `$event.currentTarget` as
+`EventTarget | null`, which has no `value`. The mirrored line casts it to the
+element's class, which you import as a type from the family's subpath:
+
+```vue
+<script setup lang="ts">
+import type { HelixInput } from '@fusion.dev/helix/input'
+</script>
+```

package/content/without-a-bundler.mdx

@@ -32,10 +32,10 @@ own URL. Copy the whole `dist` folder and link `helix.css`. We checked this in
 Chromium: one `<link>` makes five requests, and every layer resolves.
 
 *Until August 24, 2026, this page listed `tokens.css` and `base.css` without
-`primitives.css`. `tokens.css` refers to a primitive 297 times and imports
-nothing. If you followed the old instructions, all 185 semantic tokens are
-declared and every color resolves to `rgba(0, 0, 0, 0)`. If your page looks
-unstyled in that way, link `helix.css`.*
+`primitives.css`. `tokens.css` refers to the primitives throughout and imports
+nothing. If you followed the old instructions, every semantic token is declared
+and every color resolves to `rgba(0, 0, 0, 0)`. If your page looks unstyled in
+that way, link `helix.css`.*
 
 `elements.css` matters most on a page with no bundler. Without a bundler, the
 module graph loads over the network, so the markup is on the page longer before
@@ -48,9 +48,11 @@ package made its import relative. Only a bundler resolves a bare specifier in an
 
 `@fusion.dev/helix` imports its dependencies by bare specifiers, such as
 `@fusion.dev/helix-core` and `lit`. A browser resolves a bare specifier only
-through an import map, and the elements import 97 separate subpaths of
-`@fusion.dev/helix-headless`. An import map would need an entry for each one,
-and for each subpath of `lit`.
+through an import map. The elements import a separate subpath of
+`@fusion.dev/helix-headless` for each family, and the package's `exports` maps
+each one to an `index.js` in a folder of its own, so an import map would need an
+entry for each one. A subpath of `lit` is the path of its file, so one `"lit/"` entry
+covers all of them.
 
 To use the elements, load them through a bundler, as
 [Installation](./installation) shows. A CDN that rewrites bare specifiers into

package/dist/index.d.ts

@@ -1,6 +1,4 @@
-export type { ApiMember, Element, EventDoc, Example, ExampleSource, Family, PropertyDoc, } from '@fusion.dev/helix-cem';
-export { catalog, displayName, findInCatalog, place, startCase, tierOf, } from '@fusion.dev/helix-cem';
-export { type ReferenceFamily, type ReferenceOptions, reference, referenceFamilies, } from './reference.js';
+export { type ReferenceFamily, type ReferenceManifest, type ReferenceOptions, reference, referenceFamilies, } from './reference.js';
 export { contentPath, type DocNavPage, type DocNavSection, type DocPage, type DocSection, findPage, navigation, pages, sections, } from './registry.js';
 export { findSection } from './sections.js';
 export { docSources } from './sources.generated.js';

package/dist/index.js

@@ -1,4 +1,3 @@
-export { catalog, displayName, findInCatalog, place, startCase, tierOf, } from '@fusion.dev/helix-cem';
 export { reference, referenceFamilies, } from './reference.js';
 export { contentPath, findPage, navigation, pages, sections, } from './registry.js';
 export { findSection } from './sections.js';

package/dist/pages.generated.js

@@ -62,6 +62,12 @@ export const docPages = [
         slug: 'composition',
         title: 'Composition',
     },
+    {
+        description: 'Find the Helix mistakes the browser accepts without an error, on your running pages and in your code, with a setup for Vite, React, Next.js, and CI.',
+        section: 'Tooling',
+        slug: 'diagnostics',
+        title: 'Diagnostics',
+    },
     {
         description: 'The layer, shadow, and material tokens for stacking, lifting, and translucent surfaces.',
         section: 'Foundations',
@@ -113,7 +119,7 @@ export const docPages = [
         title: 'Introduction',
     },
     {
-        description: 'Set the locale of date, time, and number controls, translate the built-in words, and lay out pages right to left.',
+        description: 'Set the locale of date, time, and number controls, translate the built-in words, lay out pages right to left, and color a rise and a fall for your market.',
         section: 'Essentials',
         slug: 'localization',
         title: 'Localization and RTL',

package/dist/reference.d.ts

@@ -21,12 +21,76 @@
  * prose under a heading, and truncating that threw away everything `Date
  * Picker` says about its three modes.
  */
-import type { HelixDeclaration, HelixManifest } from '@fusion.dev/helix-cem';
+/** An entry of one of a declaration's lists, as much as the reference prints. */
+export interface ReferenceEntry {
+    description?: string;
+    /** The class it came from, where the element inherited it. */
+    inheritedFrom?: {
+        name: string;
+    };
+    name: string;
+    type?: {
+        text?: string;
+    };
+}
+/** A field or a method. */
+export interface ReferenceMember extends ReferenceEntry {
+    default?: string;
+    kind?: string;
+    privacy?: string;
+}
+/** An element, as much of one as the reference prints. */
+export interface ReferenceDeclaration {
+    /** `fieldName` pairs an attribute with the property it sets. */
+    attributes?: Array<{
+        fieldName?: string;
+        name: string;
+    }>;
+    cssParts?: ReferenceEntry[];
+    cssProperties?: ReferenceEntry[];
+    cssStates?: ReferenceEntry[];
+    description?: string;
+    events?: ReferenceEntry[];
+    /** The family the element joins from another package, from `@family`. */
+    helix?: {
+        family?: string;
+    };
+    members?: ReferenceMember[];
+    slots?: ReferenceEntry[];
+    summary?: string;
+    superclass?: {
+        name: string;
+    };
+    tagName?: string;
+}
+/** A `custom-elements.json`, as much of one as the reference reads. */
+export interface ReferenceManifest {
+    modules?: Array<{
+        declarations?: ReferenceDeclaration[];
+        path?: string;
+    }>;
+}
+/** `app-header` becomes `App Header`, and `qr-code` becomes `QR Code`. */
+export declare const startCase: (slug: string) => string;
+/** The family and part a declaration belongs to, from where its file is. */
+export declare const place: (path: string | undefined) => {
+    family: string;
+    part: string;
+};
+/**
+ * The family a declaration belongs to: the one its `@family` names, and the
+ * one its folder names where it names none.
+ */
+export declare const familyOf: (declaration: {
+    helix?: {
+        family?: string;
+    };
+}, path: string | undefined) => string;
 /**
  * An example, as much of one as a markdown reference prints.
  *
- * Structural rather than the catalog's `Example`, so this module does not
- * import from one that imports it. Anything the catalog returns satisfies it.
+ * Structural rather than the catalog's `Example`, which is
+ * `@fusion.dev/helix-cem`'s. Anything the catalog returns satisfies it.
  */
 export interface ReferenceExample {
     css: string;
@@ -80,7 +144,7 @@ export interface ReferenceOptions {
 export interface ReferenceFamily {
     family: string;
     parts: Array<{
-        declaration: HelixDeclaration;
+        declaration: ReferenceDeclaration;
         part: string;
     }>;
 }
@@ -91,7 +155,7 @@ export interface ReferenceFamily {
  * the thing that holds the others, and `item` before `root` is alphabetical
  * order telling you about the alphabet rather than about the component.
  */
-export declare const referenceFamilies: (manifest: HelixManifest) => ReferenceFamily[];
+export declare const referenceFamilies: (manifest: ReferenceManifest) => ReferenceFamily[];
 /**
  * A manifest, as the markdown reference for everything in it.
  *
@@ -103,4 +167,4 @@ export declare const referenceFamilies: (manifest: HelixManifest) => ReferenceFa
  * does: a document about the accordion should not say Accordion twice before
  * its first sentence. More than one and the headings are what separate them.
  */
-export declare const reference: (manifest: HelixManifest, options?: ReferenceOptions) => string;
+export declare const reference: (manifest: ReferenceManifest, options?: ReferenceOptions) => string;

package/dist/reference.js

@@ -1,4 +1,14 @@
-import { place, startCase } from '@fusion.dev/helix-cem';
+const INITIALISMS = new Set(['api', 'css', 'html', 'id', 'qr', 'ui', 'url']);
+export const startCase = (slug) => slug
+    .split('-')
+    .filter(Boolean)
+    .map((word) => INITIALISMS.has(word) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+export const place = (path) => {
+    const [, family = '', part = ''] = /^src\/([^/]+)\/([^/]+)\//.exec(path ?? '') ?? [];
+    return { family, part };
+};
+export const familyOf = (declaration, path) => declaration.helix?.family ?? place(path).family;
 const INFRASTRUCTURE = new Set(['HelixElement']);
 const isPublic = (member) => member.privacy !== 'private' &&
     member.privacy !== 'protected' &&
@@ -21,10 +31,11 @@ export const referenceFamilies = (manifest) => {
             if (!declaration.tagName) {
                 continue;
             }
-            const { family, part } = place(module.path);
+            const family = familyOf(declaration, module.path);
             if (!family) {
                 continue;
             }
+            const { part } = place(module.path);
             families.set(family, [...(families.get(family) ?? []), { declaration, part }]);
         }
     }