@fusion.dev/helix-docs 0.186.1 → 0.188.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.186.1",
+  "version": "0.188.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,14 +36,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix": "0.186.1",
-    "@fusion.dev/helix-cem": "0.186.1",
-    "@fusion.dev/helix-headless": "0.186.1",
-    "@fusion.dev/helix-icons": "0.186.1",
-    "@fusion.dev/helix-map": "0.186.1",
-    "@fusion.dev/helix-styles": "0.186.1",
-    "@fusion.dev/helix-testing": "0.186.1",
-    "@fusion.dev/helix-theme": "0.186.1",
+    "@fusion.dev/helix": "0.188.0",
+    "@fusion.dev/helix-cem": "0.188.0",
+    "@fusion.dev/helix-headless": "0.188.0",
+    "@fusion.dev/helix-icons": "0.188.0",
+    "@fusion.dev/helix-map": "0.188.0",
+    "@fusion.dev/helix-styles": "0.188.0",
+    "@fusion.dev/helix-testing": "0.188.0",
+    "@fusion.dev/helix-theme": "0.188.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.63.0"

package/dist/catalog.d.ts

@@ -1,194 +0,0 @@
-/**
- * The component catalog: manifests and example markup, as one shape a reader
- * can render.
- *
- * **Pure, and it lives here for the same reason `reference()` does.** Reading
- * the manifests and the `.examples/*.html` files off disk is the caller's job,
- * because a content package that touched the filesystem would trace itself
- * into every consumer's server bundle.
- *
- * Two sources and no third: the manifests describe the API, and the example
- * files hold the markup. Nothing about a component is written down here, which
- * is what keeps a site from drifting away from the library it documents.
- */
-import type { HelixManifest } from '@fusion.dev/helix-cem';
-export interface ApiMember {
-    description: string;
-    name: string;
-    /**
-     * Where the platform feature this is built on is specified, if it is one.
-     *
-     * Optional here and required on `PropertyDoc`, because a property always has
-     * the field even when it is empty and a slot or a part is built on nothing.
-     * It is on the member rather than only on the property so the Read table can
-     * carry a mark: `form` and `labels` are read-only and are the two members in
-     * the library that most need one.
-     */
-    references?: {
-        label: string;
-        url: string;
-    }[];
-    type: string;
-}
-/**
- * A property, which carries a default where an attribute does not.
- *
- * Separate from `ApiMember` rather than an optional field on it, because a slot
- * and a CSS part have no default and a column of empty cells is a table saying
- * the data is missing rather than that the concept does not apply.
- */
-export interface PropertyDoc {
-    default: string;
-    description: string;
-    name: string;
-    /** Whether it is a getter, so a reader is not invited to set it. */
-    readonly: boolean;
-    /** Where the platform feature this is built on is specified. */
-    references: {
-        label: string;
-        url: string;
-    }[];
-    type: string;
-}
-export interface EventDoc {
-    description: string;
-    name: string;
-    reactProp: string;
-    type: string;
-}
-export interface Element {
-    attributes: ApiMember[];
-    cssParts: ApiMember[];
-    cssProperties: ApiMember[];
-    cssStates: ApiMember[];
-    description: string;
-    /**
-     * The entry that registers the element, under the tier's package: the
-     * family's own, such as `filter-input`, or one of its own where the family's
-     * leaves it out, such as `filter-input/menu`.
-     */
-    entry: string;
-    events: EventDoc[];
-    label: string;
-    methods: ApiMember[];
-    /** Role within the family. `Root` for its primary element. */
-    part: string;
-    properties: PropertyDoc[];
-    slots: ApiMember[];
-    summary: string;
-    tagName: string;
-    tier: 'headless' | 'styled';
-}
-export interface Example {
-    /** The example's own stylesheet, or empty where it needs none. */
-    css: string;
-    /** One line from the example's `@summary` comment, or empty where unwritten. */
-    description: string;
-    html: string;
-    label: string;
-    /**
-     * The frame layout this example asks for, where it asks for one.
-     *
-     * Absent on almost every example, which is the design rather than an
-     * oversight: the reference picks `centered` and only the exceptions say
-     * otherwise, so what is written down is the handful of facts that differ
-     * rather than a table of defaults kept by hand. A consumer that has no
-     * layouts can ignore it.
-     */
-    layout?: string;
-    /**
-     * The least height the preview pane should give this example, in pixels.
-     *
-     * Present on the six overlay families and nowhere else. Height is derived
-     * from what the frame drew, so a declared one is a fact that can go stale;
-     * these are the examples where there is nothing to derive, because what they
-     * open is `position: fixed` and excluded from measurement by design.
-     */
-    min?: number;
-    slug: string;
-    /**
-     * The same example authored in TSX, which is a file and never a conversion.
-     *
-     * **Both syntaxes are authored, neither derived.** A derived example is a
-     * function of its twin rather than a thing anybody wrote, and converting the
-     * HTML mechanically does not work: an example carrying a `<script>` becomes
-     * a JSX fragment with a `<script>` in it, which is a syntax error rather
-     * than a bad example.
-     *
-     * `helix component`'s `examples-paired` holds the two files to each other and
-     * `check:spec:visual-parity` holds the two pictures to each other.
-     */
-    tsx: string;
-    /**
-     * Which tier the example shows, read from what it renders.
-     *
-     * Off the markup rather than off the filename, the same test `helix component`'s `tokens`
-     * uses to know a headless example's stylesheet may write raw values: an
-     * example is a headless one when it renders a `helix-headless-` element.
-     * Both tiers call theirs `preview.html`, the package directory carrying the
-     * tier, so the name cannot answer and this is the only fact available.
-     */
-    tier: 'headless' | 'styled';
-}
-export interface Family {
-    aliases: string[];
-    /** What the component is for, from `@category`. The gallery groups on it. */
-    category: string;
-    documentation: string;
-    elements: Element[];
-    examples: Example[];
-    /**
-     * The entries of other families whose elements a page writes inside this
-     * one, such as `option` for Select: the family does not register them, so
-     * the page imports them beside it. The reference's usage lists them under
-     * the family's own entries.
-     *
-     * Read from the import lines the family's descriptions show, where each
-     * container says what to import beside it. See "A container does not
-     * register another family's children" in `helix/CONVENTIONS.md`.
-     */
-    imports: string[];
-    label: string;
-    since: string;
-    slug: string;
-    /** The family's source directory, relative to the repository root. */
-    source: string;
-    status: string;
-    summary: string;
-}
-/**
- * One example as it sits on disk, before this decides what to call it.
- *
- * An example is up to two files, `<slug>.html` and an optional `<slug>.css`.
- * The HTML is the list: a stylesheet on its own is not an example, and
- * `helix component`'s `examples` fails on one whose markup is missing rather than showing a
- * sandbox with a stylesheet and nothing to style.
- *
- * The pair is what the sandbox already shows, `index.html` beside `styles.css`,
- * so the second file is the one the reader is looking at rather than a build
- * step. Never an inline `style` attribute instead: it is unreachable from a
- * stylesheet, cannot express a hover or a media query, and teaches a reader to
- * write the one thing the library exists to avoid.
- */
-export interface ExampleSource {
-    css: string;
-    /** Family folder the example was found in. */
-    family: string;
-    html: string;
-    /** File name without its extension: `preview`, `headless`, `cards.headless`. */
-    slug: string;
-    /** The authored TSX beside the HTML, never a conversion of it. */
-    tsx: string;
-}
-/**
- * Every family across the given manifests, alphabetical, each with its elements
- * and examples.
- *
- * The family a declaration belongs to comes from where its file is rather than
- * from its tag name, which is the same reasoning `place()` carries for the
- * reference: `helix-button-group` is one family and `helix-tab` is a part
- * of another, and nothing in the name says which.
- */
-export declare const catalog: (manifests: HelixManifest[], examples?: ExampleSource[]) => Family[];
-/** The family of a given slug, from an already-built catalog. */
-export declare const findInCatalog: (families: Family[], slug: string) => Family | undefined;

package/dist/catalog.js

@@ -1,163 +0,0 @@
-import { displayName, startCase, tierOf } from './naming.js';
-import { place } from './reference.js';
-const CANONICAL = 'preview';
-const HEADLESS = 'headless';
-const HEADLESS_SUFFIX = /\.headless$/;
-const withoutUndefined = (text) => text
-    .split('|')
-    .map((part) => part.trim())
-    .filter((part) => part !== 'undefined')
-    .join(' | ');
-const PLATFORM_CALLBACK = /Callback$/;
-const isPublic = (row) => row.privacy === undefined || row.privacy === 'public';
-const properties = (rows) => (rows ?? [])
-    .filter((row) => row.kind === 'field' && isPublic(row) && row.static !== true)
-    .map((row) => ({
-    default: row.default === 'undefined' ? '' : (row.default ?? ''),
-    description: row.description ?? '',
-    name: row.name ?? '',
-    readonly: row.readonly === true,
-    references: row.helix?.references ?? [],
-    type: withoutUndefined(row.type?.text ?? ''),
-}));
-const methods = (rows) => (rows ?? [])
-    .filter((row) => row.kind === 'method' && isPublic(row) && !PLATFORM_CALLBACK.test(row.name ?? ''))
-    .map((row) => {
-    const args = (row.parameters ?? [])
-        .map((arg) => `${arg.name ?? ''}: ${arg.type?.text ?? 'unknown'}`)
-        .join(', ');
-    return {
-        description: row.description ?? '',
-        name: row.name ?? '',
-        type: `(${args}) => ${row.return?.type?.text ?? 'void'}`,
-    };
-});
-const members = (rows) => (rows ?? []).map((row) => ({
-    description: row.description ?? '',
-    name: row.name ?? '',
-    type: withoutUndefined(row.type?.text ?? ''),
-}));
-const ANNOTATION = /^[^\S\n]*<!--\s*@[\s\S]*?-->[^\S\n]*\n?/gm;
-const withoutAnnotations = (html) => html.replace(ANNOTATION, '').trimStart();
-const examplesOf = (slug, declared, sources) => {
-    const described = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.description ?? '']));
-    const layouts = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.layout ?? '']));
-    const minimums = new Map((declared?.examples ?? []).map((entry) => [entry.slug ?? '', entry.min ?? 0]));
-    return (sources
-        .filter((source) => source.family === slug)
-        .sort((a, b) => {
-        const pairOf = (slug) => slug === HEADLESS ? CANONICAL : slug.replace(HEADLESS_SUFFIX, '');
-        const twin = (slug) => (slug === HEADLESS || HEADLESS_SUFFIX.test(slug) ? 1 : 0);
-        const left = pairOf(a.slug);
-        const right = pairOf(b.slug);
-        if (left !== right) {
-            return left === CANONICAL ? -1 : right === CANONICAL ? 1 : left.localeCompare(right);
-        }
-        return twin(a.slug) - twin(b.slug);
-    })
-        .map((source) => {
-        const layout = layouts.get(source.slug);
-        const min = minimums.get(source.slug);
-        const mirrored = source.slug === HEADLESS ? CANONICAL : source.slug.replace(HEADLESS_SUFFIX, '');
-        return {
-            css: source.css,
-            description: described.get(source.slug) ?? '',
-            html: withoutAnnotations(source.html),
-            label: startCase(mirrored),
-            ...(layout ? { layout } : {}),
-            ...(min ? { min } : {}),
-            slug: source.slug,
-            tier: (source.html.includes('<helix-headless-') ? 'headless' : 'styled'),
-            tsx: source.tsx,
-        };
-    }));
-};
-const entriesOf = (manifest) => {
-    const entries = new Map();
-    for (const module of manifest.modules ?? []) {
-        const entry = /^src\/(.+)\/index\.ts$/.exec(module.path ?? '')?.[1];
-        if (!entry) {
-            continue;
-        }
-        for (const exported of module.exports ?? []) {
-            const from = exported.declaration?.module?.replace(/\.[jt]s$/, '');
-            const held = from === undefined ? undefined : entries.get(from);
-            if (from !== undefined && (held === undefined || entry.length < held.length)) {
-                entries.set(from, entry);
-            }
-        }
-    }
-    return entries;
-};
-export const catalog = (manifests, examples = []) => {
-    const byFamily = new Map();
-    const entryOf = new Map();
-    for (const manifest of manifests) {
-        const entries = entriesOf(manifest);
-        for (const module of manifest.modules ?? []) {
-            for (const declaration of module.declarations ?? []) {
-                if (!declaration.tagName) {
-                    continue;
-                }
-                const { family } = place(module.path);
-                if (!family) {
-                    continue;
-                }
-                byFamily.set(family, [...(byFamily.get(family) ?? []), declaration]);
-                entryOf.set(declaration, entries.get((module.path ?? '').replace(/\.[jt]s$/, '')) ?? family);
-            }
-        }
-    }
-    return [...byFamily.entries()]
-        .map(([slug, entries]) => {
-        const root = entries.find((entry) => entry.tagName === `helix-${slug}`) ??
-            entries[0];
-        const named = (tag) => entries.find((entry) => entry.tagName === tag);
-        const roots = [named(`helix-${slug}`), named(`helix-${HEADLESS}-${slug}`)].filter((entry) => entry !== undefined);
-        return {
-            aliases: [...new Set(roots.flatMap((entry) => entry.helix?.aliases ?? []))],
-            category: root.helix?.category ?? '',
-            documentation: root.helix?.documentation ?? '',
-            elements: entries
-                .map((entry) => ({
-                attributes: members(entry.attributes),
-                cssParts: members(entry.cssParts),
-                cssProperties: members(entry.cssProperties),
-                cssStates: members(entry.cssStates),
-                description: entry.description ?? '',
-                entry: entryOf.get(entry) ?? slug,
-                events: (entry.events ?? []).map((event) => ({
-                    description: event.description ?? '',
-                    name: event.name ?? '',
-                    reactProp: event.reactProp ?? `on${event.name ?? ''}`,
-                    type: event.type?.text ?? '',
-                })),
-                label: displayName(entry.tagName),
-                methods: methods(entry.members),
-                part: entry.helix?.part ?? '',
-                properties: properties(entry.members),
-                slots: members(entry.slots),
-                summary: entry.summary ?? '',
-                tagName: entry.tagName,
-                tier: tierOf(entry.tagName),
-            }))
-                .sort((a, b) => Number(a.tier === 'headless') - Number(b.tier === 'headless') ||
-                a.tagName.localeCompare(b.tagName)),
-            examples: examplesOf(slug, root.helix, examples),
-            imports: importsOf(slug, entries),
-            label: startCase(slug),
-            since: root.helix?.since ?? '',
-            slug,
-            source: root.helix?.source ?? '',
-            status: root.helix?.status ?? '',
-            summary: root.summary ?? '',
-        };
-    })
-        .sort((a, b) => a.label.localeCompare(b.label));
-};
-const importsOf = (slug, declarations) => [
-    ...new Set(declarations.flatMap((declaration) => [...(declaration.description ?? '').matchAll(/import '@fusion\.dev\/helix\/([a-z-]+)'/g)]
-        .map((match) => match[1] ?? '')
-        .filter((entry) => entry !== '' && entry !== slug))),
-].sort();
-export const findInCatalog = (families, slug) => families.find((family) => family.slug === slug);

package/dist/naming.d.ts

@@ -1,14 +0,0 @@
-/**
- * Display names for components.
- *
- * The product is Helix, so every component being called "HelixCard" inside the
- * Helix site is noise: it repeats the one thing the reader already knows on
- * every row of the sidebar. The tag keeps its prefix, because that is a real
- * identifier a consumer types.
- */
-/** `app-header` becomes `App Header`, and `qr-code` becomes `QR Code`. */
-export declare const startCase: (slug: string) => string;
-/** `helix-app-header` becomes `App Header`, `helix-headless-card` becomes `Card`. */
-export declare const displayName: (tagName: string) => string;
-/** Which tier a tag belongs to, read from the prefix rather than the manifest. */
-export declare const tierOf: (tagName: string) => 'headless' | 'styled';

package/dist/naming.js

@@ -1,8 +0,0 @@
-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 displayName = (tagName) => startCase(tagName.replace(/^helix-(?:headless-)?/, ''));
-export const tierOf = (tagName) => tagName.startsWith('helix-headless-') ? 'headless' : 'styled';