Skip to content
5 changes: 5 additions & 0 deletions Documentation/ComponentPicker/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,11 @@ Components with descriptors today:
| `Tag` | `Tag` | `severity`, `rounded` |
| `Skeleton` | `Skeleton` | `width`, `height`, `borderRadius`, `circle` |
| `ProgressSpinner` | `ProgressSpinner` | `aria-label` |
| `Breadcrumbs` | `Breadcrumbs` | `aria-label` |
| `Message` | `Message` | `severity` |
| `Toolbar` | `Toolbar` | `orientation`, `aria-label` |
| `ToolbarGroup` | `ToolbarGroup` | `orientation` |
| `ToolbarSeparator` | `ToolbarSeparator` | `orientation` |
| `TextInput` | `TextInput` | `placeholder`, `invalid`, `disabled`, `readOnly`, `type` |
| `TextArea` | `TextArea` | `placeholder`, `rows`, `invalid`, `disabled`, `readOnly` |
| `Dialog` | `Dialog` | `title`, `placement`, `width`, `okLabel`, `cancelLabel` |
Expand Down
128 changes: 66 additions & 62 deletions Source/Common/Breadcrumbs.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ import {
import type { ExactPartKeys } from '../types/ExactPartKeys';
import type { PartsOf } from '../types/parts';
import { classNames } from '../ClassNames/classNames';
import { describeComponent } from '../configuration/identity/describeComponent';
import { useComponentPresentation } from '../configuration/identity/useComponentPresentation';

/** Attributes a consumer may hand to one {@link Breadcrumbs} part: class, style, title and data attributes. */
export type BreadcrumbsPartAttributes = Pick<
Expand Down Expand Up @@ -61,6 +63,10 @@ export interface BreadcrumbsProps {
pt?: BreadcrumbsParts;
}

const breadcrumbsDescriptor = describeComponent<BreadcrumbsProps>('Breadcrumbs', [
{ name: 'aria-label', label: 'Accessible label', type: 'string' },
]);

/**
* A breadcrumb trail.
*
Expand All @@ -69,66 +75,64 @@ export interface BreadcrumbsProps {
* a destination. The trail is an ordered list inside a navigation landmark, so it can be jumped to
* and its length announced.
*/
export const Breadcrumbs = ({
items,
separator = '/',
'aria-label': ariaLabel,
className,
pt,
}: BreadcrumbsProps) => (
// React Aria renders the ordered list; the navigation landmark around it is ours, because a
// trail a screen-reader user cannot jump to is only a list of links.
<nav aria-label={ariaLabel}>
<AriaBreadcrumbs
{...pt?.root}
className={classNames('cratis-breadcrumbs', pt?.root?.className, className)}
data-cratis-part='root'
data-cratis-component='Breadcrumbs'
>
{items.map((item, index) => {
const current = index === items.length - 1;
return (
<AriaBreadcrumb
key={`${index}-${String(item.href ?? '')}`}
{...pt?.item}
className={classNames('cratis-breadcrumbs__item', pt?.item?.className)}
data-cratis-part='item'
data-selected={current || undefined}
>
{/*
* Every segment is a link, including the current page: React Aria hands
* aria-current="page" and the disabled state to the last one through its link
* context, so a segment rendered as plain text would silently lose both.
*/}
<AriaLink
{...pt?.link}
href={current ? undefined : item.href}
onPress={current ? undefined : item.onNavigate}
className={classNames(
'cratis-breadcrumbs__link',
pt?.link?.className,
)}
data-cratis-part='link'
data-selected={current || undefined}
>
{item.label}
</AriaLink>
{!current && (
<span
{...pt?.separator}
aria-hidden='true'
className={classNames(
'cratis-breadcrumbs__separator',
pt?.separator?.className,
)}
data-cratis-part='separator'
export const Breadcrumbs = (props: BreadcrumbsProps) => {
const [presentation, marker] = useComponentPresentation(breadcrumbsDescriptor, props);
const { items, separator = '/', 'aria-label': ariaLabel, className, pt } = presentation;
return (
// React Aria renders the ordered list; the navigation landmark around it is ours, because a
// trail a screen-reader user cannot jump to is only a list of links.
<nav aria-label={ariaLabel}>
<AriaBreadcrumbs
{...pt?.root}
{...marker}
className={classNames('cratis-breadcrumbs', pt?.root?.className, className)}
data-cratis-part='root'
>
{items.map((item, index) => {
const current = index === items.length - 1;
return (
<AriaBreadcrumb
key={`${index}-${String(item.href ?? '')}`}
{...pt?.item}
className={classNames('cratis-breadcrumbs__item', pt?.item?.className)}
data-cratis-part='item'
data-selected={current || undefined}
>
{separator}
</span>
)}
</AriaBreadcrumb>
);
})}
</AriaBreadcrumbs>
</nav>
);
{/*
* Every segment is a link, including the current page: React Aria hands
* aria-current="page" and the disabled state to the last one through its link
* context, so a segment rendered as plain text would silently lose both.
*/}
<AriaLink
{...pt?.link}
href={current ? undefined : item.href}
onPress={current ? undefined : item.onNavigate}
className={classNames(
'cratis-breadcrumbs__link',
pt?.link?.className,
)}
data-cratis-part='link'
data-selected={current || undefined}
>
{item.label}
</AriaLink>
{!current && (
<span
{...pt?.separator}
aria-hidden='true'
className={classNames(
'cratis-breadcrumbs__separator',
pt?.separator?.className,
)}
data-cratis-part='separator'
>
{separator}
</span>
)}
</AriaBreadcrumb>
);
})}
</AriaBreadcrumbs>
</nav>
);
};
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

import React, { type ReactElement } from 'react';
import { Breadcrumbs } from '../../../Common/Breadcrumbs';
import { Message } from '../../../Display/Message';
import { Toolbar } from '../../../Toolbar/Toolbar';
import { ToolbarGroup } from '../../../Toolbar/ToolbarGroup';
import { ToolbarSeparator } from '../../../Toolbar/ToolbarSeparator';
import type { PresentationPropertyDescriptor } from '../../../configuration/identity/PresentationPropertyDescriptor';
import type { PresentationPropertyValue } from '../../../configuration/identity/PresentationPropertyValue';

interface PresentationComponentCase {
component: string;
element: ReactElement;
defaults: ReactElement;
properties: readonly PresentationPropertyDescriptor<Record<string, unknown>>[];
current: Record<string, PresentationPropertyValue>;
preview: Record<string, PresentationPropertyValue>;
read: (element: HTMLElement) => unknown;
rendered: unknown;
previewed: unknown;
defaultRendered: unknown;
}

export const commonAndToolbarComponents: readonly PresentationComponentCase[] = [
{
component: 'Breadcrumbs',
element: <Breadcrumbs aria-label='Example trail' items={[{ label: <strong>Example Project</strong> }]} separator={<span>›</span>} />,
defaults: <Breadcrumbs items={[]} />,
properties: [{ name: 'aria-label', label: 'Accessible label', type: 'string' }],
current: { 'aria-label': 'Example trail' },
preview: { 'aria-label': 'Preview trail' },
read: (element) => element.parentElement!.getAttribute('aria-label'),
rendered: 'Example trail',
previewed: 'Preview trail',
defaultRendered: null,
},
{
component: 'Message',
element: <Message severity='info' text={<strong>Example status</strong>} />,
defaults: <Message />,
properties: [
{ name: 'severity', label: 'Severity', type: 'enum', values: ['info', 'success', 'warn', 'error', 'secondary', 'contrast'], defaultValue: 'info' },
],
current: { severity: 'info' },
preview: { severity: 'error' },
read: (element) => [element.dataset.severity, element.getAttribute('role'), element.querySelector('[data-cratis-part="icon"]')!.textContent],
rendered: ['info', 'status', 'ⓘ'],
previewed: ['error', 'alert', '⨯'],
defaultRendered: ['info', 'status', 'ⓘ'],
},
{
component: 'Toolbar',
element: <Toolbar orientation='horizontal' aria-label='Example tools'><span>Example tool</span></Toolbar>,
defaults: <Toolbar><span>Example tool</span></Toolbar>,
properties: [
{ name: 'orientation', label: 'Orientation', type: 'enum', values: ['vertical', 'horizontal'], defaultValue: 'vertical' },
{ name: 'aria-label', label: 'Accessible label', type: 'string' },
],
current: { orientation: 'horizontal', 'aria-label': 'Example tools' },
preview: { orientation: 'vertical', 'aria-label': 'Preview tools' },
read: (element) => [element.dataset.orientation, element.getAttribute('aria-orientation'), element.getAttribute('aria-label'), element.classList.contains('cratis:flex-row')],
rendered: ['horizontal', 'horizontal', 'Example tools', true],
previewed: ['vertical', 'vertical', 'Preview tools', false],
defaultRendered: ['vertical', 'vertical', 'Tools', false],
},
{
component: 'ToolbarGroup',
element: <ToolbarGroup orientation='horizontal'><span>Example tool</span></ToolbarGroup>,
defaults: <ToolbarGroup />,
properties: [
{ name: 'orientation', label: 'Orientation', type: 'enum', values: ['vertical', 'horizontal'], defaultValue: 'vertical' },
],
current: { orientation: 'horizontal' },
preview: { orientation: 'vertical' },
read: (element) => [element.dataset.orientation, element.classList.contains('cratis:flex-row')],
rendered: ['horizontal', true],
previewed: ['vertical', false],
defaultRendered: ['vertical', false],
},
{
component: 'ToolbarSeparator',
element: <ToolbarSeparator orientation='horizontal' />,
defaults: <ToolbarSeparator />,
properties: [
{ name: 'orientation', label: 'Orientation', type: 'enum', values: ['vertical', 'horizontal'], defaultValue: 'vertical' },
],
current: { orientation: 'horizontal' },
preview: { orientation: 'vertical' },
read: (element) => [element.dataset.orientation, element.getAttribute('aria-orientation'), element.classList.contains('toolbar-separator--in-horizontal')],
rendered: ['horizontal', 'vertical', true],
previewed: ['vertical', 'horizontal', false],
defaultRendered: ['vertical', 'horizontal', false],
},
];
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
// Copyright (c) Cratis. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

// @vitest-environment jsdom

import React, { act } from 'react';
import {
knownComponentDescriptors,
previewPresentationChanges,
registeredComponentFor,
} from '../../configuration/identity/componentInstances';
import type { PresentationChange } from '../../configuration/identity/PresentationChange';
import { describeComponentElement } from '../describeComponentElement';
import { commonAndToolbarComponents } from './given/common_and_toolbar_components';
import { click, hover, mountScreen, startPicking, unmountScreen, type ScreenInTheDom } from './given/a_screen_in_the_dom';

for (const example of commonAndToolbarComponents) {
describe(`when picking a ${example.component}`, () => {
let screen: ScreenInTheDom;
let element: HTMLElement;

beforeEach(async () => {
screen = await mountScreen(<>{example.element}{example.element}</>);
element = screen.container.querySelector<HTMLElement>(`[data-cratis-component="${example.component}"]`)!;
});

afterEach(async () => {
screen.picker().cancel();
await unmountScreen(screen);
});

it('should register only its typed presentation properties and allowed values', () => {
registeredComponentFor(element)!.descriptor.properties.should.deep.equal(example.properties);
});

it('should make its static descriptor discoverable', () => {
knownComponentDescriptors().find((descriptor) => descriptor.component === example.component)!
.should.equal(registeredComponentFor(element)!.descriptor);
});

it('should report current values through the picker', async () => {
const pending = await startPicking(screen);
await hover(element);
await click(element);
const picked = (await pending.result)!;
picked.component.should.equal(example.component);
picked.presentationProperties.map(({ name, value, editable }) => ({ name, value, editable }))
.should.deep.equal(Object.entries(example.current).map(([name, value]) => ({ name, value, editable: true })));
});

it('should read registered values rather than DOM attributes', () => {
element.setAttribute('data-orientation', 'DOM-only');
element.setAttribute('data-severity', 'DOM-only');
element.setAttribute('aria-label', 'DOM-only');
Object.fromEntries(describeComponentElement(element).presentationProperties.map(({ name, value }) => [name, value]))
.should.deep.equal(example.current);
});

it('should preview and revert without changing registered props or another instance', async () => {
const changes: PresentationChange[] = Object.entries(example.preview).map(([property, to]) => ({
property, from: example.current[property], to,
}));
const original = registeredComponentFor(element)!.props;
const other = screen.container.querySelectorAll<HTMLElement>(`[data-cratis-component="${example.component}"]`)[1];
let revert!: () => void;
[example.read(element)].should.deep.equal([example.rendered]);
await act(async () => { revert = previewPresentationChanges(element, changes); });
[example.read(element)].should.deep.equal([example.previewed]);
[example.read(other)].should.deep.equal([example.rendered]);
registeredComponentFor(element)!.props.should.equal(original);
Object.fromEntries(describeComponentElement(element).presentationProperties.map(({ name, value }) => [name, value]))
.should.deep.equal(example.current);
await act(async () => { revert(); revert(); });
[example.read(element)].should.deep.equal([example.rendered]);
});

it('should preserve defaults while reporting unset props as editable', async () => {
await act(async () => screen.root.render(example.defaults));
const defaultElement = screen.container.querySelector<HTMLElement>(`[data-cratis-component="${example.component}"]`)!;
[example.read(defaultElement)].should.deep.equal([example.defaultRendered]);
describeComponentElement(defaultElement).presentationProperties.map(({ name, value, editable }) => ({ name, value, editable }))
.should.deep.equal(example.properties.map(({ name }) => ({ name, value: undefined, editable: true })));
});

it('should unregister when unmounted', async () => {
await act(async () => screen.root.render(<></>));
[registeredComponentFor(element)].should.deep.equal([undefined]);
});
});
}
Loading
Loading