@cratis/scene.components 0.1.0

package/editors/SceneFilterPanel.tsx

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo, useRef, useState } from 'react';
+import { FilterPanel, useFilterState } from '@cratis/components/Filter';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { stringProperty } from '../properties';
+import { filterDefinitions } from './filterDefinitions';
+
+/**
+ * The `Cratis.Components:filterPanel` component - `FilterPanel` from `@cratis/components/Filter`.
+ *
+ * `FilterPanel` is a portal anchored to a button: it renders next to whatever opened it, which means it
+ * cannot be placed on a screen on its own. So this adapter is the whole control - the toggle button and
+ * the panel it anchors - and a screen places one element instead of having to model an anchor
+ * relationship the element tree has no way to express.
+ *
+ * Selection state comes from the library's own `useFilterState`, so the toggling, clearing and range
+ * behavior is the library's rather than a second implementation of it here.
+ */
+export function SceneFilterPanel({ element, slots }: RegisteredComponentProps) {
+    const filters = useMemo(() => filterDefinitions(element.properties), [element.properties]);
+    const anchorRef = useRef<HTMLButtonElement>(null);
+    const [isOpen, setIsOpen] = useState(false);
+    const state = useFilterState(filters);
+
+    return (
+        <>
+            <button type='button' ref={anchorRef} data-scene-id={element.id} onClick={() => setIsOpen(open => !open)}>
+                {stringProperty(element.properties, 'label') ?? 'Filters'}
+            </button>
+            <FilterPanel
+                isOpen={isOpen}
+                filters={filters}
+                filterValues={state.filterValues}
+                rangeValues={state.rangeValues}
+                customValues={state.customValues}
+                searchPlaceholder={stringProperty(element.properties, 'searchPlaceholder')}
+                expandedFilterKey={state.expandedFilterKey}
+                anchorRef={anchorRef}
+                onClose={() => setIsOpen(false)}
+                onFilterToggle={state.handleToggleFilter}
+                onFilterClear={state.handleClearFilter}
+                onRangeChange={state.handleRangeChange}
+                onExpandedFilterChange={state.setExpandedFilterKey}
+                onCustomValueChange={state.handleCustomValueChange}
+            >
+                {slots.content}
+            </FilterPanel>
+        </>
+    );
+}

package/editors/SceneObjectContentEditor.tsx

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { ObjectContentEditor } from '@cratis/components/ObjectContentEditor';
+import { Json, JsonSchema } from '@cratis/components/types';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, objectProperty, stringProperty } from '../properties';
+import { useEditableCopy } from './useEditableCopy';
+
+/**
+ * The `Cratis.Components:objectContentEditor` component - `ObjectContentEditor` from
+ * `@cratis/components/ObjectContentEditor`.
+ *
+ * Renders an arbitrary JSON document against its schema, so nested objects and arrays are navigable and
+ * each value is edited with a control that matches its declared type. That is what makes it worth
+ * exposing to a screen at all: the alternative is a textarea full of JSON, which is not an editor.
+ *
+ * `object` and `schema` come through the property bag as plain JSON, which is exactly what they are at
+ * runtime - the conversions state that, since the property bag is typed as unknown values by definition.
+ */
+export function SceneObjectContentEditor({ element }: RegisteredComponentProps) {
+    const declared = useMemo(() => (objectProperty(element.properties, 'object') ?? {}) as unknown as Json, [element.properties]);
+    const schema = useMemo(() => (objectProperty(element.properties, 'schema') ?? {}) as unknown as JsonSchema, [element.properties]);
+    const [object, setObject] = useEditableCopy(declared);
+
+    return (
+        <ObjectContentEditor
+            object={object}
+            schema={schema}
+            editMode={booleanProperty(element.properties, 'editMode')}
+            onChange={setObject}
+            className={stringProperty(element.properties, 'className')}
+        />
+    );
+}

package/editors/SceneObjectNavigationalBar.tsx

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { ObjectNavigationalBar } from '@cratis/components/ObjectNavigationalBar';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { stringArrayProperty, stringProperty } from '../properties';
+import { useEditableCopy } from './useEditableCopy';
+
+/**
+ * The `Cratis.Components:objectNavigationalBar` component - `ObjectNavigationalBar` from
+ * `@cratis/components/ObjectNavigationalBar`.
+ *
+ * The breadcrumb trail that says where you are inside a nested document, and lets you climb back out.
+ * Clicking a crumb truncates the trail to it, which is behavior the component reports rather than
+ * performs - so this adapter holds the trail and applies the truncation, and the bar is a working
+ * breadcrumb on a screen instead of a row of inert labels.
+ *
+ * The reported index is how many segments to *keep*, not the position of the crumb clicked: the bar
+ * prepends a `Root` crumb at index 0, so clicking the first real segment reports 1. `slice(0, index)` is
+ * what that means, and it is also exactly what the back arrow asks for when it reports `length - 1`.
+ */
+export function SceneObjectNavigationalBar({ element }: RegisteredComponentProps) {
+    const declared = useMemo(() => stringArrayProperty(element.properties, 'navigationPath') ?? [], [element.properties]);
+    const [navigationPath, setNavigationPath] = useEditableCopy(declared);
+
+    return (
+        <ObjectNavigationalBar
+            navigationPath={navigationPath}
+            onNavigate={index => setNavigationPath(navigationPath.slice(0, index))}
+            className={stringProperty(element.properties, 'className')}
+        />
+    );
+}

package/editors/SceneSchemaEditor.tsx

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { SchemaEditor } from '@cratis/components/SchemaEditor';
+import { JsonSchema } from '@cratis/components/types';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { booleanProperty, objectProperty, stringProperty } from '../properties';
+import { useEditableCopy } from './useEditableCopy';
+
+/**
+ * The `Cratis.Components:schemaEditor` component - `SchemaEditor` from `@cratis/components/SchemaEditor`.
+ *
+ * Edits a JSON schema as a typed property tree rather than as text. In a Cratis application this is how
+ * an event type's shape is inspected and evolved, so `canEdit` and `canNotEditReason` are a pair worth
+ * setting together - a schema is often deliberately read-only, and saying *why* in the same place is
+ * what keeps that from looking like a bug.
+ */
+export function SceneSchemaEditor({ element }: RegisteredComponentProps) {
+    const declared = useMemo(() => (objectProperty(element.properties, 'schema') ?? {}) as unknown as JsonSchema, [element.properties]);
+    const [schema, setSchema] = useEditableCopy(declared);
+
+    return (
+        <SchemaEditor
+            schema={schema}
+            eventTypeName={stringProperty(element.properties, 'eventTypeName')}
+            canEdit={booleanProperty(element.properties, 'canEdit')}
+            canNotEditReason={stringProperty(element.properties, 'canNotEditReason')}
+            editMode={booleanProperty(element.properties, 'editMode')}
+            onChange={setSchema}
+            className={stringProperty(element.properties, 'className')}
+        />
+    );
+}

package/editors/SceneTimeMachine.tsx

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { TimeMachine } from '@cratis/components/TimeMachine';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { numberProperty } from '../properties';
+import { timeMachineVersions } from './timeMachineVersions';
+import { useEditableCopy } from './useEditableCopy';
+
+/**
+ * The `Cratis.Components:timeMachine` component - `TimeMachine` from `@cratis/components/TimeMachine`.
+ *
+ * Scrubs through successive versions of something on a timeline - which in an event-sourced application
+ * is the most natural way to look at anything, since every read model *has* a history rather than only a
+ * current value. The selected version is held here so the timeline scrubs on a screen; a host that wants
+ * to drive the selection renders the component itself.
+ */
+export function SceneTimeMachine({ element }: RegisteredComponentProps) {
+    const versions = useMemo(() => timeMachineVersions(element.properties), [element.properties]);
+    const declaredIndex = numberProperty(element.properties, 'currentVersionIndex') ?? 0;
+    const [currentVersionIndex, setCurrentVersionIndex] = useEditableCopy(declaredIndex);
+
+    return (
+        <TimeMachine
+            versions={versions}
+            currentVersionIndex={currentVersionIndex}
+            onVersionChange={setCurrentVersionIndex}
+            scrollSensitivity={numberProperty(element.properties, 'scrollSensitivity')}
+        />
+    );
+}

package/editors/filterDefinitions.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { FilterDefinition, FilterOption, FilterValue } from '@cratis/components/Filter';
+import { booleanProperty, numberProperty, objectArrayProperty, stringProperty, unionProperty } from '../properties';
+
+/** The value kinds a filter can be declared over. */
+const filterTypes = ['string', 'number', 'date', 'custom'] as const;
+
+/**
+ * Reads a `filters` property into the `FilterDefinition` list `FilterPanel` renders.
+ *
+ * A definition needs a `key` and a `label`; an entry without both is dropped, since a filter with no key
+ * has nothing to filter on and one with no label cannot be shown. Everything else is optional and falls
+ * through to the panel's own defaults.
+ */
+export function filterDefinitions(properties: Record<string, unknown>): FilterDefinition[] {
+    const entries = objectArrayProperty(properties, 'filters') ?? [];
+
+    return entries
+        .map((entry): FilterDefinition | undefined => {
+            const key = stringProperty(entry, 'key');
+            const label = stringProperty(entry, 'label');
+            if (key === undefined || label === undefined) return undefined;
+
+            return {
+                key,
+                label,
+                type: unionProperty(entry, 'type', filterTypes),
+                multi: booleanProperty(entry, 'multi'),
+                options: filterOptions(entry),
+                searchable: booleanProperty(entry, 'searchable'),
+                searchPlaceholder: stringProperty(entry, 'searchPlaceholder'),
+                buckets: numberProperty(entry, 'buckets'),
+            };
+        })
+        .filter((definition): definition is FilterDefinition => definition !== undefined);
+}
+
+/**
+ * Reads one filter's selectable options. An option's `value` is what gets applied and its `key` is what
+ * the panel tracks selection by; `value` falls back to the key so the common case of a plain string
+ * choice needs only `key` and `label`.
+ */
+function filterOptions(entry: Record<string, unknown>): FilterOption[] | undefined {
+    const options = objectArrayProperty(entry, 'options');
+    if (options === undefined) return undefined;
+
+    return options
+        .map((option): FilterOption | undefined => {
+            const key = stringProperty(option, 'key');
+            const label = stringProperty(option, 'label');
+            if (key === undefined || label === undefined) return undefined;
+
+            const value: FilterValue = stringProperty(option, 'value') ?? numberProperty(option, 'value') ?? booleanProperty(option, 'value') ?? key;
+            return { key, label, value, count: numberProperty(option, 'count') };
+        })
+        .filter((option): option is FilterOption => option !== undefined);
+}

package/editors/for_SceneObjectNavigationalBar/when_navigating_back_up_the_trail.tsx

@@ -0,0 +1,18 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { externalComponent } from '../../given';
+import { SceneObjectNavigationalBar } from '../SceneObjectNavigationalBar';
+
+describe('when navigating back up the trail', () => {
+    beforeEach(() => {
+        const element = externalComponent('Cratis.Components:objectNavigationalBar', { navigationPath: ['shipping', 'address', 'street'] });
+        render(<SceneObjectNavigationalBar element={element} slots={{}} />);
+        fireEvent.click(screen.getByText('address'));
+    });
+
+    it('should keep the crumb that was clicked', () => screen.getByText('address').textContent!.should.equal('address'));
+    it('should keep everything above it', () => screen.getByText('shipping').textContent!.should.equal('shipping'));
+    it('should drop everything below it', () => (screen.queryByText('street') === null).should.be.true);
+});

package/editors/for_filterDefinitions/when_reading_filter_definitions.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { filterDefinitions } from '../filterDefinitions';
+
+describe('when reading filter definitions', () => {
+    describe('and a filter declares options', () => {
+        const definitions = filterDefinitions({
+            filters: [
+                {
+                    key: 'status',
+                    label: 'Status',
+                    type: 'string',
+                    multi: true,
+                    options: [
+                        { key: 'draft', label: 'Draft', count: 12 },
+                        { key: 'approved', label: 'Approved', value: 'Approved' },
+                    ],
+                },
+            ],
+        });
+
+        it('should read the filter', () => definitions.should.have.lengthOf(1));
+        it('should read the declared type', () => definitions[0].type!.should.equal('string'));
+        it('should read the multi flag', () => definitions[0].multi!.should.equal(true));
+        it('should fall back to the option key as its value', () => definitions[0].options![0].value!.should.equal('draft'));
+        it('should use a declared option value when there is one', () => definitions[0].options![1].value!.should.equal('Approved'));
+        it('should read the option count', () => definitions[0].options![0].count!.should.equal(12));
+    });
+
+    describe('and an entry is missing a key or a label', () => {
+        const definitions = filterDefinitions({
+            filters: [{ key: 'status', label: 'Status' }, { label: 'No key' }, { key: 'noLabel' }],
+        });
+
+        it('should keep only the filters that can be shown and applied', () =>
+            definitions.map(definition => definition.key).should.deep.equal(['status']));
+    });
+
+    describe('and a filter declares a type outside the allowed set', () => {
+        const definitions = filterDefinitions({ filters: [{ key: 'status', label: 'Status', type: 'colour' }] });
+
+        it('should leave the type unset rather than passing an unknown one through', () => (definitions[0].type === undefined).should.be.true);
+    });
+
+    describe('and no filters property is set', () => {
+        it('should read no filters', () => filterDefinitions({}).should.deep.equal([]));
+    });
+});

package/editors/for_timeMachineVersions/when_reading_versions.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { timeMachineVersions } from '../timeMachineVersions';
+
+describe('when reading versions', () => {
+    describe('and every entry is complete', () => {
+        const versions = timeMachineVersions({
+            versions: [
+                { id: 'v1', label: 'Registered', timestamp: '2026-01-05T10:00:00.000Z', content: 'First' },
+                { id: 'v2', label: 'Approved', timestamp: 1767700800000, content: 'Second' },
+            ],
+        });
+
+        it('should read every version', () => versions.should.have.lengthOf(2));
+        it('should read an ISO timestamp', () => versions[0].timestamp.toISOString().should.equal('2026-01-05T10:00:00.000Z'));
+        it('should read an epoch timestamp', () => versions[1].timestamp.getTime().should.equal(1767700800000));
+        it('should read the content as text', () => versions[0].content!.should.equal('First'));
+    });
+
+    describe('and an entry is incomplete or unparseable', () => {
+        const versions = timeMachineVersions({
+            versions: [
+                { id: 'v1', label: 'Registered', timestamp: '2026-01-05T10:00:00.000Z' },
+                { label: 'No id', timestamp: '2026-01-05T10:00:00.000Z' },
+                { id: 'v3', timestamp: '2026-01-05T10:00:00.000Z' },
+                { id: 'v4', label: 'No timestamp' },
+                { id: 'v5', label: 'Unparseable', timestamp: 'the fifth of January' },
+            ],
+        });
+
+        it('should keep only the entries that can be placed on a timeline', () => versions.map(version => version.id).should.deep.equal(['v1']));
+        it('should default missing content to empty text', () => versions[0].content!.should.equal(''));
+    });
+
+    describe('and no versions property is set', () => {
+        it('should read no versions', () => timeMachineVersions({}).should.deep.equal([]));
+    });
+});

package/editors/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './useEditableCopy';
+export * from './timeMachineVersions';
+export * from './filterDefinitions';
+export * from './SceneObjectContentEditor';
+export * from './SceneObjectNavigationalBar';
+export * from './SceneSchemaEditor';
+export * from './SceneTimeMachine';
+export * from './SceneFilterPanel';

package/editors/timeMachineVersions.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Version } from '@cratis/components/TimeMachine';
+import { numberProperty, objectArrayProperty, stringProperty } from '../properties';
+
+/**
+ * Reads a `versions` property into the `Version` list `TimeMachine` renders.
+ *
+ * An entry without an `id`, a `label` and a parseable `timestamp` is dropped rather than defaulted,
+ * because `TimeMachine`'s whole job is to place versions on a timeline: a version invented at the epoch
+ * would not be a slightly wrong entry, it would silently reorder every real one around it. A dropped
+ * entry is visibly one item short; a fabricated one is a timeline that lies.
+ *
+ * `content` is rendered as text. A version whose content is a whole element tree is not something a
+ * property bag can carry, and pretending otherwise would be the wrong seam - that belongs in a screen
+ * template, not in a property.
+ */
+export function timeMachineVersions(properties: Record<string, unknown>): Version[] {
+    const entries = objectArrayProperty(properties, 'versions') ?? [];
+
+    return entries
+        .map((entry): Version | undefined => {
+            const id = stringProperty(entry, 'id');
+            const label = stringProperty(entry, 'label');
+            const timestamp = timestampOf(entry);
+            if (id === undefined || label === undefined || timestamp === undefined) return undefined;
+
+            return { id, label, timestamp, content: stringProperty(entry, 'content') ?? '' };
+        })
+        .filter((version): version is Version => version !== undefined);
+}
+
+/**
+ * Reads an entry's `timestamp`, accepting both the ISO string a `.play` screen writes and the epoch
+ * number a serializer may produce, and rejecting anything that does not parse into a real date.
+ */
+function timestampOf(entry: Record<string, unknown>): Date | undefined {
+    const value = stringProperty(entry, 'timestamp') ?? numberProperty(entry, 'timestamp');
+    if (value === undefined) return undefined;
+
+    const timestamp = new Date(value);
+    return Number.isNaN(timestamp.getTime()) ? undefined : timestamp;
+}

package/editors/useEditableCopy.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useState } from 'react';
+
+/**
+ * Keeps a locally editable copy of a value a screen declares, resetting it whenever the declared value
+ * itself changes.
+ *
+ * The editors in `@cratis/components` are controlled components: `ObjectContentEditor`, `SchemaEditor`
+ * and `TimeMachine` all render what they are given and report changes through a callback. A Scene screen
+ * can only *declare* the starting value - a property bag has no way to receive a callback - so without
+ * somewhere to put the result, every one of these would render as a dead surface that discards every
+ * keystroke. Local state is what makes them behave like the editors they are while a screen is being
+ * designed; a host that needs the edits for real reads them off its own model, not off the screen.
+ *
+ * The reset is deliberately done during render rather than in an effect: Studio rewrites an element's
+ * properties as the designer types, and an effect-based reset would show one frame of the previous
+ * value every time.
+ */
+export function useEditableCopy<T>(source: T): [T, (value: T) => void] {
+    const [edited, setEdited] = useState(source);
+    const [lastSource, setLastSource] = useState(source);
+
+    if (lastSource !== source) {
+        setLastSource(source);
+        setEdited(source);
+        return [source, setEdited];
+    }
+
+    return [edited, setEdited];
+}

package/for_cratisComponents/when_rendering_a_screen_through_the_real_renderer.tsx

@@ -0,0 +1,37 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { expect } from 'chai';
+import { render, screen } from '@testing-library/react';
+import { ExternalComponent } from '@cratis/scene.model';
+import { SceneElementView } from '@cratis/scene.react';
+import { externalComponent } from '../given';
+import { cratisComponents } from '../cratisComponents';
+import { clearBindings } from '../bindings';
+
+function withContent(element: ExternalComponent, content: ExternalComponent[]): ExternalComponent {
+    return { ...element, slots: { content } };
+}
+
+const invoices = withContent(externalComponent('Cratis.Components:page', { title: 'Invoices', showTitle: true }), [
+    externalComponent('Cratis.Components:toolbar', {}),
+    externalComponent('Cratis.Components:dataTable', { query: 'AllInvoices', emptyMessage: 'No invoices' }),
+]);
+
+describe('when rendering a screen through the real renderer', () => {
+    beforeEach(() => {
+        clearBindings();
+        render(<SceneElementView element={invoices} registry={cratisComponents} resolveBinding={() => undefined} />);
+    });
+
+    afterEach(() => clearBindings());
+
+    it('should resolve every component name against this package registry', () =>
+        expect(screen.getByRole('heading', { name: 'Invoices' })).to.exist);
+
+    it('should render the unbound table as a placeholder', () =>
+        expect(screen.getByText("Unresolved query binding 'AllInvoices' on Cratis.Components:dataTable")).to.exist);
+
+    it('should render no unresolved-component fallback', () =>
+        (document.querySelector('[data-scene-unresolved-component]') === null).should.be.true);
+});

package/for_cratisComponentsPackage/when_a_profile_ranks_it_above_the_packages_it_layers_on.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UiProfile } from '@cratis/scene.model';
+import { PackageCatalog, resolveComponentName } from '@cratis/scene.engine';
+import { cratisComponentsPackageManifest } from '../cratisComponentsPackage';
+
+const profile: UiProfile = { name: 'test', targetPlatform: 'web', packages: ['core', 'PrimeReact', 'Cratis.Components'] };
+
+const catalog: PackageCatalog = {
+    core: ['text', 'button', 'card'],
+    PrimeReact: ['button', 'table', 'dialog'],
+    'Cratis.Components': cratisComponentsPackageManifest.components,
+};
+
+describe('when a profile ranks it above the packages it layers on', () => {
+    describe('and it declares a name PrimeReact also declares', () => {
+        const resolution = resolveComponentName('table', profile, catalog)!;
+
+        it('should resolve to this package', () => resolution.package.should.equal('Cratis.Components'));
+        it('should record PrimeReact as shadowed rather than discarding it', () => resolution.shadows.should.deep.equal(['PrimeReact']));
+    });
+
+    describe('and it declares the dialog name PrimeReact also declares', () => {
+        const resolution = resolveComponentName('dialog', profile, catalog)!;
+
+        it('should resolve to the Arc-aware dialog rather than the bare PrimeReact one', () => resolution.package.should.equal('Cratis.Components'));
+        it('should record PrimeReact as shadowed', () => resolution.shadows.should.deep.equal(['PrimeReact']));
+    });
+
+    describe('and it declares a name nothing else does', () => {
+        const resolution = resolveComponentName('dataPage', profile, catalog)!;
+
+        it('should resolve to this package', () => resolution.package.should.equal('Cratis.Components'));
+        it('should shadow nothing', () => resolution.shadows.should.deep.equal([]));
+    });
+
+    describe('and a name it does not declare is asked for', () => {
+        const resolution = resolveComponentName('card', profile, catalog)!;
+
+        it('should fall through to the highest-priority package that does', () => resolution.package.should.equal('core'));
+    });
+
+    describe('and a screen qualifies the name with the package explicitly', () => {
+        const resolution = resolveComponentName('PrimeReact.table', profile, catalog)!;
+
+        it('should resolve to the named package even though this one outranks it', () => resolution.package.should.equal('PrimeReact'));
+    });
+});

package/for_cratisComponentsPackage/when_resolving_its_dependencies.ts

@@ -0,0 +1,68 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScenePackage } from '@cratis/scene.model';
+import { isPackageSelectionValid, resolvePackageDependencies } from '@cratis/scene.engine';
+import { cratisComponentsPackageManifest } from '../cratisComponentsPackage';
+
+/**
+ * A styling package declaring nothing but itself - enough for `Cratis.Components` to depend on, and no
+ * more, so this spec fails only when *this* package's declaration is wrong.
+ */
+const tailwind: ScenePackage = {
+    name: 'Tailwind',
+    version: '4.3.3',
+    kind: PackageKind.Styling,
+    dependencies: [],
+    components: [],
+    layouts: [],
+    screenTemplates: [],
+    dialogTemplates: [],
+    themes: [],
+};
+
+/** The base component library `Cratis.Components` wraps, at the version this repository pins. */
+const primeReact: ScenePackage = {
+    name: 'PrimeReact',
+    version: '10.9.8',
+    kind: PackageKind.ComponentLibrary,
+    dependencies: [{ name: 'Tailwind' }],
+    components: ['button', 'table', 'dialog'],
+    layouts: [],
+    screenTemplates: [],
+    dialogTemplates: [],
+    themes: ['lara-light-blue', 'lara-dark-blue'],
+};
+
+describe('when resolving its dependencies', () => {
+    const catalog = [tailwind, primeReact, cratisComponentsPackageManifest];
+    const selection = resolvePackageDependencies(['Cratis.Components'], catalog);
+
+    it('should order every package it depends on before it', () =>
+        selection.packages.should.deep.equal(['Tailwind', 'PrimeReact', 'Cratis.Components']));
+
+    it('should report the packages it pulls in on the caller behalf', () => selection.added.should.deep.equal(['Tailwind', 'PrimeReact']));
+    it('should report nothing missing', () => selection.missing.should.deep.equal([]));
+    it('should report no version conflict', () => selection.versionConflicts.should.deep.equal([]));
+    it('should report no cycle', () => selection.cycles.should.deep.equal([]));
+    it('should be a valid selection', () => isPackageSelectionValid(selection).should.be.true);
+
+    describe('and neither dependency is in the catalog', () => {
+        const withoutDependencies = resolvePackageDependencies(['Cratis.Components'], [cratisComponentsPackageManifest]);
+
+        it('should report both as missing rather than silently ordering around them', () =>
+            withoutDependencies.missing.should.deep.equal([
+                { package: 'Cratis.Components', dependsOn: 'PrimeReact' },
+                { package: 'Cratis.Components', dependsOn: 'Tailwind' },
+            ]));
+    });
+
+    describe('and PrimeReact is older than the range the token layer needs', () => {
+        const older = resolvePackageDependencies(['Cratis.Components'], [tailwind, { ...primeReact, version: '10.8.0' }, cratisComponentsPackageManifest]);
+
+        it('should report the version conflict', () =>
+            older.versionConflicts.should.deep.equal([
+                { package: 'Cratis.Components', dependsOn: 'PrimeReact', requiredRange: '>=10.9.0', actualVersion: '10.8.0' },
+            ]));
+    });
+});

package/for_cratisComponentsPackage/when_validating_the_bundle.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { componentRegistryKey, validatePackageBundle } from '@cratis/scene.react';
+import { cratisComponentsPackage, cratisComponentsPackageManifest } from '../cratisComponentsPackage';
+import { cratisComponentsPackageName } from '../cratisComponents';
+
+describe('when validating the bundle', () => {
+    const problems = validatePackageBundle(cratisComponentsPackage);
+
+    it('should report no problems', () => problems.should.deep.equal([]));
+
+    it('should register an implementation for every declared component', () => {
+        const missing = cratisComponentsPackageManifest.components.filter(
+            name => !(componentRegistryKey(cratisComponentsPackageName, name) in cratisComponentsPackage.components)
+        );
+        missing.should.deep.equal([]);
+    });
+
+    it('should key every registration under this package name', () => {
+        const foreign = Object.keys(cratisComponentsPackage.components).filter(key => !key.startsWith(`${cratisComponentsPackageName}:`));
+        foreign.should.deep.equal([]);
+    });
+
+    it('should declare every registered component', () => {
+        const declared = new Set(cratisComponentsPackageManifest.components);
+        const undeclared = Object.keys(cratisComponentsPackage.components).filter(
+            key => !declared.has(key.slice(`${cratisComponentsPackageName}:`.length))
+        );
+        undeclared.should.deep.equal([]);
+    });
+
+    it('should declare no layouts, screen templates, dialog templates or themes', () => {
+        cratisComponentsPackageManifest.layouts.should.deep.equal([]);
+        cratisComponentsPackageManifest.screenTemplates.should.deep.equal([]);
+        cratisComponentsPackageManifest.dialogTemplates.should.deep.equal([]);
+        cratisComponentsPackageManifest.themes.should.deep.equal([]);
+    });
+});