@cratis/scene.primereact 0.1.0

package/for_applyPrimeReactTheme/when_swapping_the_theme_stylesheet.ts

@@ -0,0 +1,81 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { applyPrimeReactTheme } from '../theme';
+
+describe('when swapping the theme stylesheet', () => {
+    afterEach(() => {
+        document.getElementById('theme-link')?.remove();
+    });
+
+    describe('and the application already declared a theme link', () => {
+        let swapped: boolean;
+
+        beforeEach(() => {
+            const link = document.createElement('link');
+            link.setAttribute('rel', 'stylesheet');
+            link.setAttribute('id', 'theme-link');
+            link.setAttribute('href', '/assets/themes/lara-light-blue/theme.css');
+            document.head.appendChild(link);
+            swapped = applyPrimeReactTheme('soho-dark');
+        });
+
+        it('should report that it swapped', () => {
+            swapped.should.be.true;
+        });
+
+        it('should rewrite only the theme folder, leaving the application in charge of where themes are served from', () => {
+            document.getElementById('theme-link')!.getAttribute('href')!.should.equal('/assets/themes/soho-dark/theme.css');
+        });
+
+        it('should leave exactly one theme link behind', () => {
+            document.querySelectorAll('#theme-link').should.have.lengthOf(1);
+        });
+    });
+
+    describe('and the theme name also appears elsewhere in the url', () => {
+        beforeEach(() => {
+            const link = document.createElement('link');
+            link.setAttribute('id', 'theme-link');
+            link.setAttribute('href', '/nano/themes/nano/theme.css');
+            document.head.appendChild(link);
+            applyPrimeReactTheme('mira');
+        });
+
+        it('should rewrite the theme folder and not the rest of the path', () => {
+            document.getElementById('theme-link')!.getAttribute('href')!.should.equal('/nano/themes/mira/theme.css');
+        });
+    });
+
+    describe('and no theme link exists yet', () => {
+        let swapped: boolean;
+
+        beforeEach(() => {
+            swapped = applyPrimeReactTheme('mira');
+        });
+
+        it('should report that it swapped', () => {
+            swapped.should.be.true;
+        });
+
+        it('should create the link rather than refuse to theme the page', () => {
+            document.getElementById('theme-link')!.getAttribute('href')!.should.equal('primereact/resources/themes/mira/theme.css');
+        });
+    });
+
+    describe('and the theme is unknown', () => {
+        let swapped: boolean;
+
+        beforeEach(() => {
+            swapped = applyPrimeReactTheme('lara-light-chartreuse');
+        });
+
+        it('should report that it did not swap', () => {
+            swapped.should.be.false;
+        });
+
+        it('should not create a link to a stylesheet that does not exist', () => {
+            (document.getElementById('theme-link') === null).should.be.true;
+        });
+    });
+});

package/for_columnDefinitions/when_deriving_columns.ts

@@ -0,0 +1,80 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent, HorizontalAlignment, VerticalAlignment, Visibility } from '@cratis/scene.model';
+import { columnDefinitions } from '../data';
+
+function table(properties: Record<string, unknown>, slots: ExternalComponent['slots'] = {}): ExternalComponent {
+    return {
+        id: 'table',
+        name: 'table',
+        properties,
+        slots,
+        componentName: 'PrimeReact:table',
+        visibility: Visibility.Visible,
+        isEnabled: true,
+        opacity: 1,
+        size: {},
+        zIndex: 0,
+        minimumSize: {},
+        maximumSize: {},
+        margin: { left: 0, top: 0, right: 0, bottom: 0 },
+        horizontalAlignment: HorizontalAlignment.Stretch,
+        verticalAlignment: VerticalAlignment.Stretch,
+    };
+}
+
+const rows = [{ name: 'Ada', role: 'Engineer' }];
+
+describe('when deriving columns', () => {
+    describe('and the table has nested column children', () => {
+        const element = table({ columns: ['ignored'] }, { columns: [{ id: 'c1', properties: { field: 'name', header: 'Name', sortable: true } }] });
+
+        it('should use them in preference to anything else, because they are the most explicit statement', () => {
+            columnDefinitions(element, rows).should.deep.equal([{ field: 'name', header: 'Name', sortable: true }]);
+        });
+    });
+
+    describe('and a nested column child gives no header', () => {
+        const element = table({}, { columns: [{ id: 'c1', properties: { field: 'name' } }] });
+
+        it('should label it with the field rather than leaving it blank', () => {
+            columnDefinitions(element, rows).should.deep.equal([{ field: 'name', header: 'name', sortable: false }]);
+        });
+    });
+
+    describe('and the table configures its columns as records', () => {
+        const element = table({ columns: [{ field: 'role', header: 'Role' }] });
+
+        it('should use them', () => {
+            columnDefinitions(element, rows).should.deep.equal([{ field: 'role', header: 'Role', sortable: false }]);
+        });
+    });
+
+    describe('and the table configures its columns as bare field names', () => {
+        const element = table({ columns: ['role'] });
+
+        it('should use each name as both field and header', () => {
+            columnDefinitions(element, rows).should.deep.equal([{ field: 'role', header: 'role', sortable: false }]);
+        });
+    });
+
+    describe('and the table configures no columns at all', () => {
+        const element = table({});
+
+        it('should infer them from the first row, so a table with data renders it', () => {
+            columnDefinitions(element, rows).should.deep.equal([
+                { field: 'name', header: 'name', sortable: false },
+                { field: 'role', header: 'role', sortable: false },
+            ]);
+        });
+    });
+
+    describe('and the table has neither columns nor rows', () => {
+        const element = table({});
+
+        it('should derive no columns rather than throwing', () => {
+            columnDefinitions(element, []).should.deep.equal([]);
+        });
+    });
+});

package/for_menuItems/when_converting_entries.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { MenuItem } from 'primereact/menuitem';
+import { toMenuItems } from '../menuItems';
+
+describe('when converting entries', () => {
+    describe('and an entry is a bare string', () => {
+        it('should use it as the label', () => {
+            toMenuItems(['File']).should.deep.equal([{ label: 'File' }]);
+        });
+    });
+
+    describe('and an entry carries submenus', () => {
+        const items = toMenuItems([{ label: 'File', icon: 'pi pi-file', items: [{ label: 'Open', items: ['Recent'] }] }]);
+
+        it('should keep the label and icon', () => {
+            items[0].label!.should.equal('File');
+            items[0].icon!.should.equal('pi pi-file');
+        });
+
+        it('should follow the nesting to any depth, because a menubar and a tiered menu differ only in depth', () => {
+            const submenu = items[0].items as MenuItem[];
+            const nested = submenu[0].items as MenuItem[];
+            nested[0].label!.should.equal('Recent');
+        });
+    });
+
+    describe('and an entry is a separator', () => {
+        it('should keep it even though it has no label', () => {
+            toMenuItems([{ separator: true }]).should.deep.equal([{ separator: true }]);
+        });
+    });
+
+    describe('and an entry has no usable label', () => {
+        it('should drop it rather than render a blank command', () => {
+            toMenuItems([{ icon: 'pi pi-file' }, 7, ['nested'], { label: 'File' }]).should.deep.equal([{ label: 'File' }]);
+        });
+    });
+});

package/for_primeReactPackage/when_inspecting_the_manifest.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind } from '@cratis/scene.model';
+import { primeReactPackageManifest } from '../primeReactPackage';
+
+describe('when inspecting the manifest', () => {
+    it('should be named the way a ui profile lists it', () => {
+        primeReactPackageManifest.name.should.equal('PrimeReact');
+    });
+
+    it('should be a component library', () => {
+        primeReactPackageManifest.kind.should.equal(PackageKind.ComponentLibrary);
+    });
+
+    it('should depend on Tailwind, because the wrappers lay themselves out with it', () => {
+        primeReactPackageManifest.dependencies.should.deep.equal([{ name: 'Tailwind' }]);
+    });
+
+    it('should name the module a host imports it from', () => {
+        primeReactPackageManifest.module!.should.equal('@cratis/scene.primereact');
+    });
+
+    it('should provide no layouts, which belong to a blueprint package', () => {
+        primeReactPackageManifest.layouts.should.deep.equal([]);
+    });
+
+    it('should provide no screen templates, which belong to a blueprint package', () => {
+        primeReactPackageManifest.screenTemplates.should.deep.equal([]);
+    });
+
+    it('should provide no dialog templates, which belong to a blueprint package', () => {
+        primeReactPackageManifest.dialogTemplates.should.deep.equal([]);
+    });
+
+    it('should declare the names Screenplay screen directives compile to', () => {
+        for (const name of ['table', 'column', 'title', 'field', 'section', 'summary', 'action']) {
+            primeReactPackageManifest.components.should.contain(name);
+        }
+    });
+});

package/for_primeReactPackage/when_inspecting_the_registry.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { componentRegistryKey } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { primeReactPackageManifest } from '../primeReactPackage';
+
+describe('when inspecting the registry', () => {
+    const keys = Object.keys(primeReactComponents);
+
+    it('should register an implementation for every declared component name', () => {
+        const missing = primeReactPackageManifest.components.filter((name) => primeReactComponents[componentRegistryKey('PrimeReact', name)] === undefined);
+        missing.should.deep.equal([]);
+    });
+
+    it('should declare every registered component name', () => {
+        const declared = new Set(primeReactPackageManifest.components);
+        const undeclared = keys.filter((key) => !declared.has(key.slice('PrimeReact:'.length)));
+        undeclared.should.deep.equal([]);
+    });
+
+    it('should qualify every registry key with the package name', () => {
+        keys.filter((key) => !key.startsWith('PrimeReact:')).should.deep.equal([]);
+    });
+
+    it('should declare every component name exactly once', () => {
+        primeReactPackageManifest.components.should.have.lengthOf(new Set(primeReactPackageManifest.components).size);
+    });
+
+    it('should name every component in lowerCamelCase', () => {
+        primeReactPackageManifest.components.filter((name) => !/^[a-z][a-zA-Z]*$/.test(name)).should.deep.equal([]);
+    });
+});

package/for_primeReactPackage/when_rendering_every_declared_component.tsx

@@ -0,0 +1,69 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { render } from '@testing-library/react';
+import { SceneElementView } from '@cratis/scene.react';
+import { primeReactComponents } from '../primeReactComponents';
+import { primeReactPackageManifest } from '../primeReactPackage';
+import { sceneComponent } from '../storyElements';
+
+/**
+ * The end-to-end check the registry spec cannot make.
+ *
+ * `validatePackageBundle` proves the manifest and the registry agree on *names*. This proves the names
+ * actually reach a component: each declared name is put through the real `SceneElementView`, the real
+ * renderer and the real registry, and must not come out as the `UnresolvedComponent` placeholder. A
+ * misspelled registry key passes every name-level check and only fails here.
+ *
+ * Each element is rendered with almost nothing configured, which is the second thing this specifies: a
+ * component whose data has not been authored yet is an ordinary state on a screen under construction, and
+ * it must render empty rather than take the whole screen down with it. This is how PrimeReact's
+ * OrganizationChart was found to throw on an empty node list.
+ */
+describe('when rendering every declared component', () => {
+    let unresolved: string[];
+    let threw: string[];
+
+    beforeEach(() => {
+        // jsdom implements no `matchMedia`, and PrimeReact's PickList calls it to pick a responsive
+        // layout. This fills the environment gap rather than papering over a defect - a real browser
+        // has always had it.
+        if (window.matchMedia === undefined) {
+            window.matchMedia = (query: string) =>
+                ({
+                    matches: false,
+                    media: query,
+                    onchange: undefined,
+                    addListener: () => undefined,
+                    removeListener: () => undefined,
+                    addEventListener: () => undefined,
+                    removeEventListener: () => undefined,
+                    dispatchEvent: () => false,
+                }) as unknown as MediaQueryList;
+        }
+
+        unresolved = [];
+        threw = [];
+
+        for (const name of primeReactPackageManifest.components) {
+            const element = sceneComponent(`element-${name}`, name, { text: name, label: name, value: name });
+            try {
+                const { container, unmount } = render(
+                    <SceneElementView element={element} registry={primeReactComponents} resolveBinding={() => undefined} />
+                );
+                if (container.querySelector('[data-scene-unresolved-component]') !== null) unresolved.push(name);
+                unmount();
+            } catch (error) {
+                threw.push(`${name}: ${(error as Error).message.split('\n')[0]}`);
+            }
+        }
+    });
+
+    it('should resolve every declared name to a real component', () => {
+        unresolved.should.deep.equal([]);
+    });
+
+    it('should render every declared component with nothing configured, rather than throwing', () => {
+        threw.should.deep.equal([]);
+    });
+});

package/for_primeReactPackage/when_resolving_a_name_core_also_declares.ts

@@ -0,0 +1,45 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageCatalog, resolveComponentName } from '@cratis/scene.engine';
+import { UiProfile } from '@cratis/scene.model';
+import { corePackageManifest } from '@cratis/scene.react';
+import { primeReactPackageManifest } from '../primeReactPackage';
+
+describe('when resolving a name core also declares', () => {
+    const profile: UiProfile = { name: 'web', targetPlatform: 'web', packages: ['core', 'PrimeReact'] };
+    const catalog: PackageCatalog = {
+        core: corePackageManifest.components,
+        PrimeReact: primeReactPackageManifest.components,
+    };
+
+    for (const name of ['text', 'button', 'card']) {
+        describe(`and the name is '${name}'`, () => {
+            const resolution = resolveComponentName(name, profile, catalog);
+
+            it('should resolve it', () => {
+                (resolution !== undefined).should.be.true;
+            });
+
+            it('should resolve to PrimeReact', () => {
+                resolution!.package.should.equal('PrimeReact');
+            });
+
+            it('should record that core was shadowed', () => {
+                resolution!.shadows.should.deep.equal(['core']);
+            });
+        });
+    }
+
+    describe('and the name is only declared by PrimeReact', () => {
+        const resolution = resolveComponentName('dataTable', profile, catalog);
+
+        it('should resolve to PrimeReact', () => {
+            resolution!.package.should.equal('PrimeReact');
+        });
+
+        it('should shadow nothing', () => {
+            resolution!.shadows.should.deep.equal([]);
+        });
+    });
+});

package/for_primeReactPackage/when_validating_the_bundle.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { validatePackageBundle } from '@cratis/scene.react';
+import { primeReactPackage } from '../primeReactPackage';
+
+describe('when validating the bundle', () => {
+    let problems: string[];
+
+    beforeEach(() => {
+        problems = validatePackageBundle(primeReactPackage);
+    });
+
+    it('should report no problems', () => {
+        problems.should.deep.equal([]);
+    });
+});

package/for_primeReactThemes/when_checking_attribution.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { primeReactThemes } from '../theme';
+
+describe('when checking attribution', () => {
+    it('should credit an author on every theme', () => {
+        primeReactThemes.filter((theme) => theme.author === undefined || theme.author === '').should.deep.equal([]);
+    });
+
+    it('should link to the author on every theme', () => {
+        primeReactThemes.filter((theme) => theme.authorUrl === undefined || theme.authorUrl === '').should.deep.equal([]);
+    });
+
+    it('should state a license on every theme', () => {
+        primeReactThemes.filter((theme) => theme.license === undefined || theme.license === '').should.deep.equal([]);
+    });
+
+    it('should credit PrimeTek, who made every one of them', () => {
+        primeReactThemes.filter((theme) => theme.author !== 'PrimeTek').should.deep.equal([]);
+    });
+
+    it('should state the license the primereact package actually ships under', () => {
+        primeReactThemes.filter((theme) => theme.license !== 'MIT').should.deep.equal([]);
+    });
+
+    it('should describe every theme for a picker', () => {
+        primeReactThemes.filter((theme) => theme.description === undefined || theme.description === '').should.deep.equal([]);
+    });
+});

package/for_primeReactThemes/when_checking_compatibility.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { incompatiblePackages } from '@cratis/scene.engine';
+import { UiProfile } from '@cratis/scene.model';
+import { primeReactThemes } from '../theme';
+
+describe('when checking compatibility', () => {
+    const profile: UiProfile = { name: 'web', targetPlatform: 'web', packages: ['core', 'PrimeReact', 'Tailwind'] };
+
+    it('should declare every theme compatible with PrimeReact', () => {
+        primeReactThemes.filter((theme) => !theme.compatibleWith.includes('PrimeReact')).should.deep.equal([]);
+    });
+
+    it('should declare every theme compatible with Tailwind', () => {
+        primeReactThemes.filter((theme) => !theme.compatibleWith.includes('Tailwind')).should.deep.equal([]);
+    });
+
+    it('should declare every theme compatible with core, which gets no implicit exemption', () => {
+        primeReactThemes.filter((theme) => !theme.compatibleWith.includes('core')).should.deep.equal([]);
+    });
+
+    it('should report no incompatibility for a profile listing all three', () => {
+        primeReactThemes.flatMap((theme) => incompatiblePackages(theme, profile)).should.deep.equal([]);
+    });
+});

package/for_primeReactThemes/when_checking_the_token_vocabulary.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { primeReactThemes } from '../theme';
+
+describe('when checking the token vocabulary', () => {
+    const vocabulary = [
+        'primary.color',
+        'primary.contrastColor',
+        'surface.background',
+        'surface.card',
+        'surface.border',
+        'surface.hover',
+        'surface.overlay',
+        'text.color',
+        'text.mutedColor',
+        'highlight.background',
+        'highlight.color',
+        'content.borderRadius',
+        'focus.ring',
+    ];
+
+    it('should give every theme the whole vocabulary', () => {
+        const incomplete = primeReactThemes
+            .filter((theme) => vocabulary.some((token) => theme.tokens?.[token] === undefined))
+            .map((theme) => theme.name);
+        incomplete.should.deep.equal([]);
+    });
+
+    it('should give every theme nothing but the vocabulary, so packages can agree on it', () => {
+        const extra = primeReactThemes.flatMap((theme) => Object.keys(theme.tokens ?? {}).filter((token) => !vocabulary.includes(token)));
+        extra.should.deep.equal([]);
+    });
+
+    it('should say whether every theme is dark', () => {
+        primeReactThemes.filter((theme) => theme.isDark === undefined).should.deep.equal([]);
+    });
+
+    it('should ship both light and dark themes', () => {
+        primeReactThemes.some((theme) => theme.isDark === true).should.be.true;
+        primeReactThemes.some((theme) => theme.isDark === false).should.be.true;
+    });
+
+    it('should mirror the value the shipped stylesheet uses for its primary color', () => {
+        primeReactThemes.find((theme) => theme.name === 'lara-light-blue')!.tokens!['primary.color'].should.equal('#3b82f6');
+    });
+
+    it('should replace the unresolved SCSS expression PrimeReact ships for the viva-dark hover surface', () => {
+        primeReactThemes.find((theme) => theme.name === 'viva-dark')!.tokens!['surface.hover'].should.equal('rgba(158, 173, 230, 0.08)');
+    });
+});

package/for_primeReactThemes/when_resolving_a_theme_stylesheet.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { primeReactThemeNames, primeReactThemeStylesheet } from '../theme';
+
+describe('when resolving a theme stylesheet', () => {
+    describe('and the theme is one this package ships', () => {
+        it('should point at the theme folder PrimeReact ships it in', () => {
+            primeReactThemeStylesheet('lara-dark-indigo')!.should.equal('primereact/resources/themes/lara-dark-indigo/theme.css');
+        });
+
+        it('should resolve a path for every theme in the catalog', () => {
+            primeReactThemeNames.filter((name) => primeReactThemeStylesheet(name) === undefined).should.deep.equal([]);
+        });
+    });
+
+    describe('and the theme is unknown', () => {
+        it('should resolve nothing rather than a path that would 404', () => {
+            (primeReactThemeStylesheet('lara-light-chartreuse') === undefined).should.be.true;
+        });
+    });
+});

package/for_properties/when_reading_a_boolean_property.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { booleanProperty } from '../properties';
+
+describe('when reading a boolean property', () => {
+    const element: SceneElement = { id: 'element', properties: { disabled: true, visible: false, filter: 'yes' } };
+
+    describe('and the property is present and a boolean', () => {
+        it('should return true when it is true', () => {
+            booleanProperty(element, 'disabled', false).should.be.true;
+        });
+
+        it('should return false when it is false rather than falling back', () => {
+            booleanProperty(element, 'visible', true).should.be.false;
+        });
+    });
+
+    describe('and the property is missing', () => {
+        it('should return undefined when no fallback was given', () => {
+            (booleanProperty(element, 'rounded') === undefined).should.be.true;
+        });
+
+        it('should return the fallback when one was given', () => {
+            booleanProperty(element, 'rounded', true).should.be.true;
+        });
+    });
+
+    describe('and the property is present but not a boolean', () => {
+        it('should treat a truthy string like a missing property', () => {
+            booleanProperty(element, 'filter', false).should.be.false;
+        });
+    });
+});

package/for_properties/when_reading_a_number_property.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 { SceneElement } from '@cratis/scene.model';
+import { numberProperty } from '../properties';
+
+describe('when reading a number property', () => {
+    const element: SceneElement = { id: 'element', properties: { rows: 5, zero: 0, size: '12', broken: Number.NaN } };
+
+    describe('and the property is present and a number', () => {
+        it('should return it', () => {
+            numberProperty(element, 'rows', 1).should.equal(5);
+        });
+
+        it('should return zero rather than falling back', () => {
+            numberProperty(element, 'zero', 10).should.equal(0);
+        });
+    });
+
+    describe('and the property is missing', () => {
+        it('should return undefined when no fallback was given', () => {
+            (numberProperty(element, 'columns') === undefined).should.be.true;
+        });
+
+        it('should return the fallback when one was given', () => {
+            numberProperty(element, 'columns', 2).should.equal(2);
+        });
+    });
+
+    describe('and the property is present but not a usable number', () => {
+        it('should treat a numeric string like a missing property', () => {
+            numberProperty(element, 'size', 16).should.equal(16);
+        });
+
+        it('should treat NaN like a missing property, because it is never a usable size', () => {
+            numberProperty(element, 'broken', 16).should.equal(16);
+        });
+    });
+});

package/for_properties/when_reading_a_string_property.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { SceneElement } from '@cratis/scene.model';
+import { stringProperty } from '../properties';
+
+describe('when reading a string property', () => {
+    const element: SceneElement = { id: 'element', properties: { label: 'Save', count: 3 } };
+
+    describe('and the property is present and a string', () => {
+        it('should return it', () => {
+            stringProperty(element, 'label')!.should.equal('Save');
+        });
+    });
+
+    describe('and the property is missing', () => {
+        it('should return undefined when no fallback was given', () => {
+            (stringProperty(element, 'placeholder') === undefined).should.be.true;
+        });
+
+        it('should return the fallback when one was given', () => {
+            stringProperty(element, 'placeholder', 'Type here').should.equal('Type here');
+        });
+    });
+
+    describe('and the property is present but not a string', () => {
+        it('should treat it exactly like a missing one', () => {
+            stringProperty(element, 'count', 'none').should.equal('none');
+        });
+    });
+});