@ctrliq/quantic-components 1.86.0 → 1.87.0

package/dist/meta/serialize.d.ts

@@ -13,11 +13,13 @@ export interface ManifestComponent extends Omit<ComponentMeta, 'props' | 'slots'
     props?: ManifestProp[];
     slots?: ManifestSlot[];
     events?: ManifestEvent[];
+    /** Derived from the children's `subComponentOf`, never hand-authored. */
+    subComponents?: string[];
 }
 export interface ComponentManifest {
     schemaVersion: number;
     generated: string;
     components: ManifestComponent[];
 }
-export declare function serializeComponent(component: ComponentMeta): ManifestComponent;
+export declare function serializeComponent(component: ComponentMeta, subComponents?: string[]): ManifestComponent;
 export declare function buildManifest(components: ComponentMeta[], generated?: string): ComponentManifest;

package/dist/meta/serialize.js

@@ -3,7 +3,7 @@ function toNamedArray(record) {
     const entries = Object.entries(record ?? {});
     return entries.length ? entries.map(([name, value]) => ({ name, ...value })) : undefined;
 }
-export function serializeComponent(component) {
+export function serializeComponent(component, subComponents) {
     const props = toNamedArray(component.props);
     const events = toNamedArray(component.events);
     const slots = toNamedArray(component.slots);
@@ -12,19 +12,36 @@ export function serializeComponent(component) {
         description: component.description,
         category: component.category,
         ...(component.ascii ? { ascii: component.ascii } : {}),
+        ...(component.experimental ? { experimental: true } : {}),
         ...(component.deprecated ? { deprecated: component.deprecated } : {}),
         ...(props ? { props } : {}),
         ...(events ? { events } : {}),
         ...(slots ? { slots } : {}),
         ...(component.examples?.length ? { examples: component.examples } : {}),
         ...(component.relatedTo?.length ? { relatedTo: component.relatedTo } : {}),
-        ...(component.subComponents?.length ? { subComponents: component.subComponents } : {}),
+        ...(component.subComponentOf ? { subComponentOf: component.subComponentOf } : {}),
+        ...(subComponents?.length ? { subComponents } : {}),
     };
 }
+/** Inverts the children's `subComponentOf` into each parent's anatomy list. */
+function collectSubComponents(components) {
+    const byParent = new Map();
+    for (const component of [...components].sort((a, b) => a.tag.localeCompare(b.tag))) {
+        if (!component.subComponentOf)
+            continue;
+        const children = byParent.get(component.subComponentOf) ?? [];
+        children.push(component.tag);
+        byParent.set(component.subComponentOf, children);
+    }
+    return byParent;
+}
 export function buildManifest(components, generated = new Date().toISOString()) {
+    const subComponents = collectSubComponents(components);
     return {
         schemaVersion: MANIFEST_SCHEMA_VERSION,
         generated,
-        components: [...components].sort((a, b) => a.tag.localeCompare(b.tag)).map(serializeComponent),
+        components: [...components]
+            .sort((a, b) => a.tag.localeCompare(b.tag))
+            .map((component) => serializeComponent(component, subComponents.get(component.tag))),
     };
 }

package/dist/meta/serialize.test.js

@@ -36,6 +36,16 @@ describe('serializeComponent', () => {
             { name: 'click', description: 'Native click', forwarded: true },
         ]);
     });
+    it('keeps experimental, and omits it when unset or false', () => {
+        expect(serializeComponent(makeComponent({ experimental: true })).experimental).toBe(true);
+        expect(serializeComponent(makeComponent({ experimental: false })).experimental).toBeUndefined();
+        expect(serializeComponent(makeComponent()).experimental).toBeUndefined();
+    });
+    it('carries experimental and deprecated together', () => {
+        const component = serializeComponent(makeComponent({ experimental: true, deprecated: { use: 'quantic-bar' } }));
+        expect(component.experimental).toBe(true);
+        expect(component.deprecated).toEqual({ use: 'quantic-bar' });
+    });
     it('keeps ascii', () => {
         expect(serializeComponent(makeComponent({ ascii: '[ foo ]' })).ascii).toBe('[ foo ]');
     });
@@ -67,6 +77,26 @@ describe('buildManifest', () => {
         ]);
         expect(components.map((component) => component.tag)).toEqual(['quantic-a', 'quantic-z']);
     });
+    it('derives each parent list from the children that name it', () => {
+        const { components } = buildManifest([
+            makeComponent({ tag: 'quantic-card' }),
+            makeComponent({ tag: 'quantic-card-title', subComponentOf: 'quantic-card' }),
+            makeComponent({ tag: 'quantic-card-image', subComponentOf: 'quantic-card' }),
+        ]);
+        const byTag = new Map(components.map((component) => [component.tag, component]));
+        expect(byTag.get('quantic-card')?.subComponents).toEqual([
+            'quantic-card-image',
+            'quantic-card-title',
+        ]);
+        expect(byTag.get('quantic-card-title')?.subComponentOf).toBe('quantic-card');
+    });
+    it('leaves a parent with no anatomy without a list', () => {
+        const { components } = buildManifest([
+            makeComponent({ tag: 'quantic-action-group', relatedTo: ['quantic-button'] }),
+            makeComponent({ tag: 'quantic-button' }),
+        ]);
+        expect(components.every((component) => component.subComponents === undefined)).toBe(true);
+    });
     it('round-trips through JSON', () => {
         const manifest = buildManifest([makeComponent({ slots: { '': { description: 'Content' } } })]);
         expect(JSON.parse(JSON.stringify(manifest))).toEqual(manifest);

package/dist/meta/slot-parity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/meta/slot-parity.test.js

@@ -0,0 +1,83 @@
+import { globSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+const SRC_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+const TAG = /@quanticElement\(\s*['"`]([^'"`]+)['"`]\s*\)/;
+const SLOT_TAG = /<slot\b([^>]*)>/g;
+const SLOT_NAME = /name=(?:"([^"]*)"|([^\s>]+))/;
+const SLOT_KEY = /(?:'([^']*)'|([A-Za-z_$][\w$]*))\s*:\s*\{/g;
+// Read from source rather than importing allMeta: that would pull in every component
+// module, and several import generated icon files that only exist after a build.
+function componentSources() {
+    return globSync('**/*.ts', { cwd: SRC_DIR })
+        .filter((file) => !/\.(stories|test|d)\.ts$/.test(file))
+        .map((file) => ({ file, source: readFileSync(join(SRC_DIR, file), 'utf-8') }));
+}
+/** Top-level keys of the `slots: { ... }` object, by brace matching from its opening. */
+function declaredSlots(source) {
+    const start = source.indexOf('slots: {');
+    if (start === -1)
+        return new Set();
+    const open = source.indexOf('{', start);
+    let depth = 0;
+    let end = open;
+    for (; end < source.length; end++) {
+        if (source[end] === '{')
+            depth++;
+        else if (source[end] === '}' && --depth === 0)
+            break;
+    }
+    const body = source.slice(open + 1, end);
+    const names = new Set();
+    let nesting = 0;
+    for (const match of body.matchAll(SLOT_KEY)) {
+        // Only keys sitting directly in the slots object name a slot; `description` and
+        // friends live one level down.
+        nesting = [...body.slice(0, match.index)].reduce((depth, character) => depth + (character === '{' ? 1 : character === '}' ? -1 : 0), 0);
+        if (nesting === 0)
+            names.add(match[1] ?? match[2]);
+    }
+    return names;
+}
+/** Rendered slot names per tag, skipping names built at runtime. */
+function renderedSlots() {
+    return componentSources().flatMap(({ file, source }) => {
+        const tag = source.match(TAG)?.[1];
+        // render-as-field.hoc.ts registers `quantic-${name}-field` for five field wrappers,
+        // so there is no static tag here to attribute slots to.
+        if (!tag || tag.includes('${'))
+            return [];
+        const names = [...source.matchAll(SLOT_TAG)]
+            .map(([, attributes]) => {
+            const name = attributes.match(SLOT_NAME);
+            // No name attribute at all is the default slot. An unquoted one is built at
+            // runtime, and has to stay distinguishable from the default so the filter below
+            // can drop it rather than miscount it.
+            return name ? (name[1] ?? name[2]) : '';
+        })
+            // `quantic-tabs` renders `name=${buttonsSlot}` and `splitter-group` renders
+            // `pane-${i}`, neither of which a manifest can enumerate.
+            .filter((name) => !name.includes('${'));
+        return names.length
+            ? [{ tag, file, names: [...new Set(names)], declared: declaredSlots(source) }]
+            : [];
+    });
+}
+describe('slot parity', () => {
+    // The manifest is the only thing anything reads. A slot that render() serves but meta
+    // does not declare is invisible to generated docs, to meta.json, and to the
+    // valid-slot-name lint rule, which skips a component that declares no slots.
+    it('declares every slot that render serves', () => {
+        const undeclared = renderedSlots().flatMap(({ tag, file, names, declared }) => {
+            const missing = names.filter((name) => !declared.has(name));
+            return missing.length
+                ? [`${tag} (${file}) is missing: ${missing.map((n) => n || '(default)').join(', ')}`]
+                : [];
+        });
+        expect(undeclared).toEqual([]);
+    });
+    it('found slots to check', () => {
+        expect(renderedSlots().length).toBeGreaterThan(40);
+    });
+});