@fusion.dev/helix-docs 0.0.0-dev → 0.0.3

package/dist/catalog.js

@@ -1,19 +1,13 @@
 import { displayName, startCase, tierOf } from './naming.js';
 import { place } from './reference.js';
-/* The headless twin's slug, and the suffix every other one carries. Named
-   because the sort and the label both ask, and a tier that has been renamed
-   once can be renamed again. */
 /**
- * The canonical example's slug, named once because three places knew it.
+ * The canonical example's slug, named once because three places ask for it.
  *
- * The tier pairing, the first-position pin and the label all had it written
- * out, and renaming `default` to `preview` broke each of them separately: the
- * pin because the old name sorted early by accident, the pairing because a twin
- * mirrors this one, the label because it reads from the name. A fact three
- * places hold is a fact that drifts, which the comment on the sort below
- * already records happening once when the tier was called `base`.
+ * The tier pairing, the first-position pin and the label all read it. A fact
+ * three places hold is a fact that drifts.
  */
 const CANONICAL = 'preview';
+/* The headless twin's slug, and the suffix every other one carries. */
 const HEADLESS = 'headless';
 const HEADLESS_SUFFIX = /\.headless$/;
 /**
@@ -24,8 +18,7 @@ const HEADLESS_SUFFIX = /\.headless$/;
  * on the host that a React consumer's server markup never had. That makes the
  * declared type `'primary' | 'neutral' | undefined`, and the `undefined` is an
  * implementation detail of how the default is expressed rather than a value
- * anyone sets. The table reads better without it, and the attribute being
- * omissible is already what "attribute" means.
+ * anyone sets.
  */
 const withoutUndefined = (text) => text
     .split('|')
@@ -48,9 +41,9 @@ const isPublic = (row) => row.privacy === undefined || row.privacy === 'public';
 /**
  * Properties, with the default each one falls back to.
  *
- * Fields rather than attributes, which is the change this page needed: an
- * attribute carries no default in the manifest, so the old table could say a
- * component took `appearance` and never what it did when you left it alone.
+ * Fields rather than attributes: an attribute carries no default in the
+ * manifest, so a table built from attributes can say a component takes a
+ * property and never what it does when you leave it alone.
  */
 const properties = (rows) => (rows ?? [])
     /* Instance fields only. A static is the class's, not an element's, and the
@@ -59,12 +52,11 @@ const properties = (rows) => (rows ?? [])
        reads to decide a control participates in a form. Thirty-five rows across
        the library, none of them anything a consumer sets on a tag. */
     /* `@internal` needs nothing here: the analyzer drops a member carrying it
-       before the manifest is written, which was worth finding out before
-       building a plugin and a filter to do the same thing twice. */
+       before the manifest is written. */
     .filter((row) => row.kind === 'field' && isPublic(row) && row.static !== true)
     .map((row) => ({
     /* `undefined` is not a default, it is the absence of one, and the
-       analyzer records the initialiser verbatim. Printed, the column reads
+       analyzer records the initializer verbatim. Printed, the column reads
        "undefined" for every optional property, which is a table telling a
        reader a word rather than a value. Blank says the same thing and says
        it quietly. */
@@ -120,11 +112,9 @@ const ANNOTATION = /^[^\S\n]*<!--\s*@[\s\S]*?-->[^\S\n]*\n?/gm;
  * The example's markup as a reader should receive it.
  *
  * `@summary` is metadata about the example rather than part of it: the cem
- * plugin lifts it into the manifest, the reference prints it as the
- * description, and it was *also* left sitting on line one of every example, so
- * the copy button handed back a comment describing the thing you had just
- * copied. Ninety-odd examples, each one telling a reader that a Helix component
- * needs a docs annotation above it.
+ * plugin lifts it into the manifest and the reference prints it as the
+ * description, so left in place it makes the copy button hand back a comment
+ * describing the thing you just copied.
  *
  * Stripped here rather than at the reader, because every consumer of the
  * catalog wants the same thing and a site that trimmed it in its own renderer
@@ -149,26 +139,18 @@ const examplesOf = (slug, declared, sources) => {
     const minimums = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.min ?? 0]));
     return (sources
         .filter((source) => source.family === slug)
-        /* `default` first, then alphabetical, with each headless twin directly
+        /* `preview` first, then alphabetical, with each headless twin directly
            behind the example it mirrors.
   
-           By slug, not by filename. This used to compare `compact-counts.html`
-           against `compact.html`, where `-` precedes `.` and so the longer name
-           sorted first, which is a list ordered by a file extension no reader
-           ever sees. The extension is not part of an example's identity:
-           `compact` and `compact-counts` are what the tabs say, and `compact`
-           comes first.
+           By slug, never by filename. Comparing `compact-counts.html` against
+           `compact.html` puts the longer name first, `-` preceding `.`, which is
+           a list ordered by a file extension no reader ever sees.
   
-           **Pairing on the mirrored name, because sorting on the raw slug only
-           ever worked by luck.** The twin used to be called `base`, and `base`
-           sorts before every family's other examples, so it landed under
-           `default` and looked deliberate. Renaming the tier to `headless` moved
-           it to the end of the list and broke two specs that had been reading
-           that accident as the rule. What the pairing is for is that the tabs
-           show the same list on both tiers, which is what `mirrored` below is
-           computing anyway: sort on it and the position is a consequence of the
-           relationship rather than of where the tier's name falls in the
-           alphabet. */
+           **Pair on the mirrored name, not on the raw slug.** Sorting on the raw
+           slug puts the twin wherever the tier's name happens to fall in the
+           alphabet, which is only ever right by luck. The tabs have to show the
+           same list on both tiers, and `mirrored` below is that relationship: sort
+           on it and the position follows from the pairing. */
         .sort((a, b) => {
         const pairOf = (slug) => slug === HEADLESS ? CANONICAL : slug.replace(HEADLESS_SUFFIX, '');
         const twin = (slug) => (slug === HEADLESS || HEADLESS_SUFFIX.test(slug) ? 1 : 0);
@@ -181,10 +163,9 @@ const examplesOf = (slug, declared, sources) => {
     })
         .map((source) => {
         /* Which styled example this one is the headless twin of. `headless` is
-         the twin of `preview`, and `<name>.headless` of `<name>`. Both names
-         have moved: the tier was `base` and the canonical example was
-         `default`, and this line is the one place that has to know the pairing
-         because a headless example is not named for itself. */
+         the twin of `preview`, and `<name>.headless` of `<name>`. This is the
+         one place that has to know the pairing, because a headless example is
+         not named for itself. */
         /* Read once and narrowed here rather than spread from the map
            directly: `get` answers `string | undefined`, and under
            `exactOptionalPropertyTypes` an optional property will not take the
@@ -196,11 +177,8 @@ const examplesOf = (slug, declared, sources) => {
             css: source.css,
             description: described.get(source.slug) ?? '',
             html: withoutAnnotations(source.html),
-            /* **The label is the file's name, with no special case left.** The
-             canonical example was called `default` and read as "Preview", a
-             translation that existed only because the name did not say what the
-             file was: it is the component's headline, not a named variant sitting
-             beside the others. Renamed, `startCase` gives "Preview" on its own.
+            /* **The label is the file's name, with no special case.** `startCase`
+             gives "Preview" for the canonical example on its own.
   
              **A headless example takes the name of the one it mirrors**, so the two
              tiers show the same list rather than a list that changes its labels

package/dist/naming.js

@@ -9,7 +9,7 @@
 /**
  * Words a slug spells in lower case that are read as letters.
  *
- * Capitalising the first letter of `qr` gives `Qr`, which is a word nobody says.
+ * Capitalizing the first letter of `qr` gives `Qr`, which is a word nobody says.
  * A slug is lower case because a URL is, and the initialism it came from is
  * lost by the time this sees it, so it has to be put back by name. Kept small
  * and explicit rather than guessed at from length: `ui`, `id` and `api` are

package/dist/pages.generated.d.ts

@@ -1,6 +1,6 @@
 /**
  * Every page this package documents, derived from the frontmatter of each MDX
- * file by `bun run docs`. Do not edit: `bun run check:docs` fails when this
+ * file by `turbo run docs`. Do not edit: `turbo run docs -- --check` fails when this
  * file and the content disagree, and the content is the source.
  */
 import type { DocPage } from './registry.js';

package/dist/pages.generated.js

@@ -75,7 +75,7 @@ export const docPages = [
         title: 'Forms and validation',
     },
     {
-        description: '103 glyphs, one geometry, and how to draw one that is not in the set.',
+        description: '105 glyphs, one geometry, and how to draw one that is not in the set.',
         section: 'Foundations',
         slug: 'iconography',
         title: 'Iconography',

package/dist/reference.js

@@ -105,7 +105,7 @@ const element = (depth, declaration, part) => {
        borrowed a stylesheet from rather than be its own. Without it a borrowed
        `--icon-button-radii` reads on the Copy Button page as a hook Copy Button
        named, and a consumer who guesses `--copy-button-radii` from that gets
-       nothing. See 290. */
+       nothing. */
     table(depth + 1, 'Custom properties', ['Property', 'From', 'Description'], cssProperties.map((one) => [
         `\`${one.name}\``,
         one.inheritedFrom?.name ? `\`${one.inheritedFrom.name}\`` : '-',

package/dist/registry.d.ts

@@ -15,7 +15,7 @@
  * mechanism npm already provides and the only one that cannot drift.
  *
  * **Nothing about a page is written here.** `pages.generated.ts` is derived
- * from each file's frontmatter by `bun run docs`, because the frontmatter is
+ * from each file's frontmatter by `turbo run docs`, because the frontmatter is
  * what a `.md` consumer receives and a second copy would be a second source of
  * truth. This module is the types and the reading of them; `sections.ts` is the
  * spine that frontmatter has nowhere to live.
@@ -34,7 +34,7 @@ export interface DocPage {
     order?: number;
     /**
      * Slug of the page this one sits under, for the one level of nesting that
-     * exists. Installation and its per-framework pages are the case.
+     * exists. Installation and Coding agents are the cases.
      */
     parent?: string;
     /**
@@ -77,7 +77,7 @@ export declare const findPage: (slug: string) => DocPage | undefined;
  * The whole sidebar: every declared section, its pages in render order, and
  * each page's children beneath it.
  *
- * A section with no pages cannot appear, because `bun run check:docs` refuses
+ * A section with no pages cannot appear, because `turbo run docs -- --check` refuses
  * to generate one. Children are alphabetical, because nesting exists for the
  * per-framework installation pages and a reader picking their framework out of
  * a list is looking one up rather than reading a sequence, and then the

package/dist/registry.js

@@ -15,7 +15,7 @@
  * mechanism npm already provides and the only one that cannot drift.
  *
  * **Nothing about a page is written here.** `pages.generated.ts` is derived
- * from each file's frontmatter by `bun run docs`, because the frontmatter is
+ * from each file's frontmatter by `turbo run docs`, because the frontmatter is
  * what a `.md` consumer receives and a second copy would be a second source of
  * truth. This module is the types and the reading of them; `sections.ts` is the
  * spine that frontmatter has nowhere to live.
@@ -30,7 +30,7 @@ const byTitle = (a, b) => a.title.toLowerCase() < b.title.toLowerCase() ? -1 : 1
  * The pages of one section, in the order a sidebar renders them.
  *
  * **Alphabetical, except a section that is a path, and except one pinned entry
- * page where a section has one.** The exemption is the same one `CLAUDE.md`
+ * page where a section has one.** The exemption is the same one `AGENTS.md`
  * grants positional arguments and middleware chains, that ordering is skipped
  * where order is semantic. Written down so a section is not silently reordered
  * by whoever next notices it is not alphabetical.
@@ -47,7 +47,7 @@ const ordered = (pages, section) => {
  * The whole sidebar: every declared section, its pages in render order, and
  * each page's children beneath it.
  *
- * A section with no pages cannot appear, because `bun run check:docs` refuses
+ * A section with no pages cannot appear, because `turbo run docs -- --check` refuses
  * to generate one. Children are alphabetical, because nesting exists for the
  * per-framework installation pages and a reader picking their framework out of
  * a list is looking one up rather than reading a sequence, and then the

package/dist/sections.d.ts

@@ -9,13 +9,9 @@
  * frontmatter to derive from, so it is written here.
  *
  * **A section with no pages is not declared.** A navigation entry is the
- * strongest existence claim a site can make, and the sections this library
- * intends to grow (Foundations, Components, Tooling) have nothing in them yet.
- * `bun run check:docs` fails on an empty section rather than rendering a
- * heading with nothing under it.
- *
- * See [`plan/23-helix-docs.md`](plan/23-helix-docs.md) for the
- * navigation this is a subset of.
+ * strongest existence claim a site can make, so a section is added with the
+ * pages that fill it rather than ahead of them. `turbo run docs -- --check` fails
+ * on an empty section rather than rendering a heading with nothing under it.
  */
 /** A top-level grouping in the sidebar. */
 export interface DocSection {

package/dist/sections.js

@@ -9,13 +9,9 @@
  * frontmatter to derive from, so it is written here.
  *
  * **A section with no pages is not declared.** A navigation entry is the
- * strongest existence claim a site can make, and the sections this library
- * intends to grow (Foundations, Components, Tooling) have nothing in them yet.
- * `bun run check:docs` fails on an empty section rather than rendering a
- * heading with nothing under it.
- *
- * See [`plan/23-helix-docs.md`](plan/23-helix-docs.md) for the
- * navigation this is a subset of.
+ * strongest existence claim a site can make, so a section is added with the
+ * pages that fill it rather than ahead of them. `turbo run docs -- --check` fails
+ * on an empty section rather than rendering a heading with nothing under it.
  */
 /**
  * Every section, in the order the sidebar renders them.

package/dist/sources.generated.d.ts

@@ -1,6 +1,6 @@
 /**
- * Every page's MDX, inlined by `bun run docs`. Do not edit: the files in
- * `content/` are the source, and `bun run check:docs` fails when this module
+ * Every page's MDX, inlined by `turbo run docs`. Do not edit: the files in
+ * `content/` are the source, and `turbo run docs -- --check` fails when this module
  * and they disagree.
  */
 export declare const docSources: Record<string, string>;