From dd31bb905803908ab382efb7aea4528ecc0d0ccf Mon Sep 17 00:00:00 2001 From: woksin Date: Sun, 22 Nov 2026 01:59:31 +0100 Subject: [PATCH 1/2] Describe presentation properties of display components for the picker --- Documentation/ComponentPicker/index.md | 6 + .../given/display_components.tsx | 107 +++++++++++++ .../when_picking_display_components.tsx | 148 ++++++++++++++++++ Source/Display/Avatar.tsx | 69 ++++---- Source/Display/Badge.tsx | 43 ++--- Source/Display/Chip.tsx | 20 +-- Source/Display/ProgressSpinner.tsx | 80 +++++----- Source/Display/Skeleton.tsx | 48 +++--- Source/Display/Tag.tsx | 50 +++--- .../when_checking_presentation_descriptors.ts | 34 ++++ 10 files changed, 465 insertions(+), 140 deletions(-) create mode 100644 Source/ComponentPicker/for_ComponentPicker/given/display_components.tsx create mode 100644 Source/ComponentPicker/for_ComponentPicker/when_picking_display_components.tsx create mode 100644 Source/for_component_identity/when_checking_presentation_descriptors.ts diff --git a/Documentation/ComponentPicker/index.md b/Documentation/ComponentPicker/index.md index c6ed98e0..62565666 100644 --- a/Documentation/ComponentPicker/index.md +++ b/Documentation/ComponentPicker/index.md @@ -133,6 +133,12 @@ Components with descriptors today: | --- | --- | --- | | `Button` | `Button` | `label`, `tooltip`, `variant`, `tone`, `shape`, `size` | | `IconButton` | `IconButton` | `tooltip`, `variant`, `tone`, `shape`, `size` | +| `Badge` | `Badge` | `severity`, `size`, `shape` | +| `Chip` | `Chip` | `label`, `removeAriaLabel` | +| `Avatar` | `Avatar` | `label`, `alt`, `size` | +| `Tag` | `Tag` | `severity`, `rounded` | +| `Skeleton` | `Skeleton` | `width`, `height`, `borderRadius`, `circle` | +| `ProgressSpinner` | `ProgressSpinner` | `aria-label` | | `TextInput` | `TextInput` | `placeholder`, `invalid`, `disabled`, `readOnly`, `type` | | `TextArea` | `TextArea` | `placeholder`, `rows`, `invalid`, `disabled`, `readOnly` | | `Dialog` | `Dialog` | `title`, `placement`, `width`, `okLabel`, `cancelLabel` | diff --git a/Source/ComponentPicker/for_ComponentPicker/given/display_components.tsx b/Source/ComponentPicker/for_ComponentPicker/given/display_components.tsx new file mode 100644 index 00000000..194d5e7d --- /dev/null +++ b/Source/ComponentPicker/for_ComponentPicker/given/display_components.tsx @@ -0,0 +1,107 @@ +// 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 { Avatar } from '../../../Display/Avatar'; +import { Badge } from '../../../Display/Badge'; +import { Chip } from '../../../Display/Chip'; +import { ProgressSpinner } from '../../../Display/ProgressSpinner'; +import { Skeleton } from '../../../Display/Skeleton'; +import { Tag } from '../../../Display/Tag'; +import type { PresentationPropertyDescriptor } from '../../../configuration/identity/PresentationPropertyDescriptor'; +import type { PresentationPropertyValue } from '../../../configuration/identity/PresentationPropertyValue'; + +interface DisplayComponentCase { + component: string; + element: ReactElement; + properties: readonly PresentationPropertyDescriptor>[]; + current: Record; + preview: Record; + read: (element: HTMLElement) => unknown; + rendered: unknown; + previewed: unknown; +} + +export const displayComponents: readonly DisplayComponentCase[] = [ + { + component: 'Badge', + element: , + properties: [ + { name: 'severity', label: 'Severity', type: 'enum', values: ['secondary', 'info', 'success', 'warn', 'danger', 'contrast'], defaultValue: 'secondary' }, + { name: 'size', label: 'Size', type: 'enum', values: ['small', 'large', 'xlarge'], defaultValue: 'small' }, + { name: 'shape', label: 'Shape', type: 'enum', values: ['circle'] }, + ], + current: { severity: 'info', size: 'large', shape: 'circle' }, + preview: { severity: 'success', size: 'xlarge', shape: undefined }, + read: (element) => [element.dataset.severity, element.dataset.size, element.dataset.shape, element.textContent], + rendered: ['info', 'large', 'circle', '7'], + previewed: ['success', 'xlarge', undefined, '7'], + }, + { + component: 'Chip', + element: undefined} />, + properties: [ + { name: 'label', label: 'Label', type: 'string' }, + { name: 'removeAriaLabel', label: 'Remove accessible name', type: 'string', defaultValue: 'Remove' }, + ], + current: { label: 'Example Project', removeAriaLabel: 'Remove example' }, + preview: { label: 'Demo Assistant', removeAriaLabel: 'Remove preview' }, + read: (element) => [element.querySelector('[data-cratis-part="label"]')?.textContent, element.querySelector('button')?.getAttribute('aria-label')], + rendered: ['Example Project', 'Remove example'], + previewed: ['Demo Assistant', 'Remove preview'], + }, + { + component: 'Avatar', + element: , + properties: [ + { name: 'label', label: 'Label', type: 'string' }, + { name: 'alt', label: 'Alternative text', type: 'string', defaultValue: '' }, + { name: 'size', label: 'Size', type: 'enum', values: ['normal', 'large', 'xlarge'], defaultValue: 'normal' }, + ], + current: { label: 'SU', alt: 'Sample User', size: 'large' }, + preview: { label: 'DA', size: 'xlarge' }, + read: (element) => [element.textContent, element.dataset.size], + rendered: ['SU', 'large'], + previewed: ['DA', 'xlarge'], + }, + { + component: 'Tag', + element: , + properties: [ + { name: 'severity', label: 'Severity', type: 'enum', values: ['secondary', 'success', 'info', 'warn', 'danger', 'contrast'], defaultValue: 'secondary' }, + { name: 'rounded', label: 'Rounded', type: 'boolean' }, + ], + current: { severity: 'info', rounded: false }, + preview: { severity: 'success', rounded: true }, + read: (element) => [element.dataset.severity, element.dataset.rounded, element.textContent], + rendered: ['info', undefined, 'Example status'], + previewed: ['success', 'true', 'Example status'], + }, + { + component: 'Skeleton', + element: , + properties: [ + { name: 'width', label: 'Width', type: 'string', defaultValue: '100%' }, + { name: 'height', label: 'Height', type: 'string', defaultValue: '1rem' }, + { name: 'borderRadius', label: 'Border radius', type: 'string' }, + { name: 'circle', label: 'Circle', type: 'boolean' }, + ], + current: { width: '4rem', height: '2rem', borderRadius: '1px', circle: false }, + preview: { width: '6rem', height: '3rem', borderRadius: '2px' }, + read: (element) => [element.style.width, element.style.height, element.style.borderRadius, element.dataset.circle], + rendered: ['4rem', '2rem', '1px', undefined], + previewed: ['6rem', '3rem', '2px', undefined], + }, + { + component: 'ProgressSpinner', + element: , + properties: [ + { name: 'aria-label', label: 'Accessible name', type: 'string', defaultValue: 'Loading' }, + ], + current: { 'aria-label': 'Loading example' }, + preview: { 'aria-label': 'Loading preview' }, + read: (element) => element.getAttribute('aria-label'), + rendered: 'Loading example', + previewed: 'Loading preview', + }, +]; diff --git a/Source/ComponentPicker/for_ComponentPicker/when_picking_display_components.tsx b/Source/ComponentPicker/for_ComponentPicker/when_picking_display_components.tsx new file mode 100644 index 00000000..103babbc --- /dev/null +++ b/Source/ComponentPicker/for_ComponentPicker/when_picking_display_components.tsx @@ -0,0 +1,148 @@ +// 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 { expect } from 'chai'; +import { vi } from 'vitest'; +import { Avatar } from '../../Display/Avatar'; +import { Badge } from '../../Display/Badge'; +import { Chip } from '../../Display/Chip'; +import { ProgressSpinner } from '../../Display/ProgressSpinner'; +import { Skeleton } from '../../Display/Skeleton'; +import { Tag } from '../../Display/Tag'; +import { + knownComponentDescriptors, + previewPresentationChanges, + registeredComponentFor, +} from '../../configuration/identity/componentInstances'; +import type { PresentationChange } from '../../configuration/identity/PresentationChange'; +import { describeComponentElement } from '../describeComponentElement'; +import { displayComponents } from './given/display_components'; +import { click, hover, mountScreen, startPicking, unmountScreen, type ScreenInTheDom } from './given/a_screen_in_the_dom'; + +for (const example of displayComponents) { + 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(`[data-cratis-component="${example.component}"]`)!; + }); + + afterEach(async () => { + screen.picker().cancel(); + await unmountScreen(screen); + }); + + it('should register exactly 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 props from the registry rather than DOM attributes', () => { + element.setAttribute('data-size', '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 the 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(`[data-cratis-component="${example.component}"]`)[1]; + let revert!: () => void; + expect(example.read(element)).to.deep.equal(example.rendered); + await act(async () => { revert = previewPresentationChanges(element, changes); }); + expect(example.read(element)).to.deep.equal(example.previewed); + expect(example.read(other)).to.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(); }); + expect(example.read(element)).to.deep.equal(example.rendered); + }); + + it('should unregister when unmounted', async () => { + await act(async () => screen.root.render(<>)); + expect(registeredComponentFor(element)).to.equal(undefined); + }); + }); +} + +describe('when previewing display presentation details', () => { + let screen: ScreenInTheDom; + + afterEach(async () => { await unmountScreen(screen); }); + + it('should preserve the existing defaults when there is no preview', async () => { + screen = await mountScreen(<>); + screen.container.querySelector('[data-cratis-component="Avatar"]')!.getAttribute('data-size')!.should.equal('normal'); + const badge = screen.container.querySelector('[data-cratis-component="Badge"]')!; + badge.getAttribute('data-severity')!.should.equal('secondary'); + badge.getAttribute('data-size')!.should.equal('small'); + screen.container.querySelector('button')!.getAttribute('aria-label')!.should.equal('Remove'); + screen.container.querySelector('[data-cratis-component="Tag"]')!.getAttribute('data-severity')!.should.equal('secondary'); + const skeleton = screen.container.querySelector('[data-cratis-component="Skeleton"]')!; + skeleton.style.width.should.equal('100%'); + skeleton.style.height.should.equal('1rem'); + screen.container.querySelector('[role="status"]')!.getAttribute('aria-label')!.should.equal('Loading'); + expect(describeComponentElement(badge).presentationProperties[0].value).to.equal(undefined); + }); + + it('should preview and revert image alternative text', async () => { + screen = await mountScreen(); + const element = screen.container.querySelector('[data-cratis-component="Avatar"]')!; + let revert!: () => void; + await act(async () => { + revert = previewPresentationChanges(element, [{ property: 'alt', from: 'Sample User', to: 'Demo Assistant' }]); + }); + element.querySelector('img')!.alt.should.equal('Demo Assistant'); + await act(async () => revert()); + element.querySelector('img')!.alt.should.equal('Sample User'); + }); + + it('should preview and revert a circular skeleton', async () => { + screen = await mountScreen(); + const element = screen.container.querySelector('[data-cratis-component="Skeleton"]')!; + let revert!: () => void; + await act(async () => { + revert = previewPresentationChanges(element, [{ property: 'circle', from: undefined, to: true }]); + }); + element.style.width.should.equal('2rem'); + element.style.borderRadius.should.equal('50%'); + element.getAttribute('data-circle')!.should.equal('true'); + await act(async () => revert()); + element.style.width.should.equal('4rem'); + element.style.borderRadius.should.equal('1px'); + expect(element.getAttribute('data-circle')).to.equal(null); + }); + + it('should preserve the chip remove callback during preview', async () => { + const onRemove = vi.fn(); + screen = await mountScreen(); + const element = screen.container.querySelector('[data-cratis-component="Chip"]')!; + await act(async () => { previewPresentationChanges(element, [{ property: 'label', from: 'Example Project', to: 'Demo Assistant' }]); }); + await click(element.querySelector('button')!); + onRemove.mock.calls.length.should.equal(1); + }); +}); diff --git a/Source/Display/Avatar.tsx b/Source/Display/Avatar.tsx index 5494957f..bad6e0f8 100644 --- a/Source/Display/Avatar.tsx +++ b/Source/Display/Avatar.tsx @@ -2,6 +2,8 @@ // Licensed under the MIT license. See LICENSE file in the project root for full license information. import type { ReactNode } from 'react'; +import { describeComponent } from '../configuration/identity/describeComponent'; +import { useComponentPresentation } from '../configuration/identity/useComponentPresentation'; /** Props for {@link Avatar}. */ export interface AvatarProps { @@ -19,36 +21,39 @@ export interface AvatarProps { className?: string; } +const avatarDescriptor = describeComponent('Avatar', [ + { name: 'label', label: 'Label', type: 'string' }, + { name: 'alt', label: 'Alternative text', type: 'string', defaultValue: '' }, + { name: 'size', label: 'Size', type: 'enum', values: ['normal', 'large', 'xlarge'] satisfies NonNullable[], defaultValue: 'normal' }, +]); + /** A user or entity avatar with an image and text/icon fallback. */ -export const Avatar = ({ - image, - label, - icon, - alt = '', - size = 'normal', - className, -}: AvatarProps) => ( - - {image ? ( - {alt} - ) : ( - - {icon ?? label} - - )} - -); +export const Avatar = (props: AvatarProps) => { + const [presentation, marker] = useComponentPresentation(avatarDescriptor, props); + const { image, label, icon, alt = '', size = 'normal', className } = presentation; + return ( + + {image ? ( + {alt} + ) : ( + + {icon ?? label} + + )} + + ); +}; diff --git a/Source/Display/Badge.tsx b/Source/Display/Badge.tsx index e16f920e..ba39d0d1 100644 --- a/Source/Display/Badge.tsx +++ b/Source/Display/Badge.tsx @@ -2,6 +2,8 @@ // Licensed under the MIT license. See LICENSE file in the project root for full license information. import type { ReactNode } from 'react'; +import { describeComponent } from '../configuration/identity/describeComponent'; +import { useComponentPresentation } from '../configuration/identity/useComponentPresentation'; /** Severity tone of a {@link Badge}. */ export type BadgeSeverity = @@ -23,23 +25,26 @@ export interface BadgeProps { children?: ReactNode; } +const badgeDescriptor = describeComponent('Badge', [ + { name: 'severity', label: 'Severity', type: 'enum', values: ['secondary', 'info', 'success', 'warn', 'danger', 'contrast'] satisfies NonNullable[], defaultValue: 'secondary' }, + { name: 'size', label: 'Size', type: 'enum', values: ['small', 'large', 'xlarge'] satisfies NonNullable[], defaultValue: 'small' }, + { name: 'shape', label: 'Shape', type: 'enum', values: ['circle'] satisfies NonNullable[] }, +]); + /** A compact count or status badge. */ -export const Badge = ({ - value, - severity = 'secondary', - size = 'small', - shape, - className, - children, -}: BadgeProps) => ( - - {value ?? children} - -); +export const Badge = (props: BadgeProps) => { + const [presentation, marker] = useComponentPresentation(badgeDescriptor, props); + const { value, severity = 'secondary', size = 'small', shape, className, children } = presentation; + return ( + + {value ?? children} + + ); +}; diff --git a/Source/Display/Chip.tsx b/Source/Display/Chip.tsx index 8fa05bb9..204a8eea 100644 --- a/Source/Display/Chip.tsx +++ b/Source/Display/Chip.tsx @@ -3,6 +3,8 @@ import type { ReactNode } from 'react'; import { useCratisIcon } from '../configuration/useCratisIcon'; +import { describeComponent } from '../configuration/identity/describeComponent'; +import { useComponentPresentation } from '../configuration/identity/useComponentPresentation'; /** Props for {@link Chip}. */ export interface ChipProps { @@ -20,21 +22,21 @@ export interface ChipProps { className?: string; } +const chipDescriptor = describeComponent('Chip', [ + { name: 'label', label: 'Label', type: 'string' }, + { name: 'removeAriaLabel', label: 'Remove accessible name', type: 'string', defaultValue: 'Remove' }, +]); + /** A labeled, optionally removable chip. */ -export const Chip = ({ - label, - icon, - removable, - onRemove, - removeAriaLabel = 'Remove', - className, -}: ChipProps) => { +export const Chip = (props: ChipProps) => { + const [presentation, marker] = useComponentPresentation(chipDescriptor, props); + const { label, icon, removable, onRemove, removeAriaLabel = 'Remove', className } = presentation; const resolveIcon = useCratisIcon(); return ( {icon && ( diff --git a/Source/Display/ProgressSpinner.tsx b/Source/Display/ProgressSpinner.tsx index 91d51993..33d11bda 100644 --- a/Source/Display/ProgressSpinner.tsx +++ b/Source/Display/ProgressSpinner.tsx @@ -2,6 +2,8 @@ // Licensed under the MIT license. See LICENSE file in the project root for full license information. import type { CSSProperties } from 'react'; +import { describeComponent } from '../configuration/identity/describeComponent'; +import { useComponentPresentation } from '../configuration/identity/useComponentPresentation'; /** Props for {@link ProgressSpinner}. */ export interface ProgressSpinnerProps { @@ -13,42 +15,46 @@ export interface ProgressSpinnerProps { 'aria-label'?: string; } +const progressSpinnerDescriptor = describeComponent('ProgressSpinner', [ + { name: 'aria-label', label: 'Accessible name', type: 'string', defaultValue: 'Loading' }, +]); + /** An indeterminate loading spinner. */ -export const ProgressSpinner = ({ - style, - className, - 'aria-label': ariaLabel = 'Loading', -}: ProgressSpinnerProps) => ( - - - - - - -); + + + ); +}; diff --git a/Source/Display/Skeleton.tsx b/Source/Display/Skeleton.tsx index f1d09f2e..3289e1e8 100644 --- a/Source/Display/Skeleton.tsx +++ b/Source/Display/Skeleton.tsx @@ -1,6 +1,9 @@ // Copyright (c) Cratis. All rights reserved. // Licensed under the MIT license. See LICENSE file in the project root for full license information. +import { describeComponent } from '../configuration/identity/describeComponent'; +import { useComponentPresentation } from '../configuration/identity/useComponentPresentation'; + /** Props for {@link Skeleton}. */ export interface SkeletonProps { /** Width, any CSS length. Defaults to `'100%'`. */ @@ -15,24 +18,29 @@ export interface SkeletonProps { className?: string; } +const skeletonDescriptor = describeComponent('Skeleton', [ + { name: 'width', label: 'Width', type: 'string', defaultValue: '100%' }, + { name: 'height', label: 'Height', type: 'string', defaultValue: '1rem' }, + { name: 'borderRadius', label: 'Border radius', type: 'string' }, + { name: 'circle', label: 'Circle', type: 'boolean' }, +]); + /** A loading placeholder that reserves content layout. */ -export const Skeleton = ({ - width = '100%', - height = '1rem', - borderRadius, - circle, - className, -}: SkeletonProps) => ( -