Skip to content
Draft
Show file tree
Hide file tree
Changes from 10 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/docs-name-exported-types.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[docs] Four docs name prop types the package exports. Selector's `options` are `SelectorOptionType[]` (`SelectorOption` is a component), SyntaxTheme's `theme` is a `SyntaxThemeDefinition`, and `useImperativeDialog` and `useImperativeAlertDialog` write their `show()` options with the exported Dialog and AlertDialog props. Toast's doc describes the card: `type`, `isAutoHide` and `autoHideDuration` are required there, and the show-only options (`uniqueID`, `collisionBehavior`, `onHide`) leave its props table, because `useToast`'s doc lists them with their defaults.

@cixzhang
6 changes: 6 additions & 0 deletions apps/docsite/src/__tests__/component-prop-controls.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,12 @@ describe('component detail prop controls', () => {
}
});

it('gives a SyntaxThemeDefinition prop the syntax theme preset control', () => {
expect(parsePropType('SyntaxThemeDefinition', 'theme')).toEqual({
kind: 'syntax-theme',
});
});

it('derives IconType options from the canonical icon registry', () => {
const control = parsePropType('IconType', 'labelIcon');

Expand Down
42 changes: 42 additions & 0 deletions apps/docsite/src/__tests__/syntax-theme-control.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax';
import {describe, expect, it} from 'vitest';
import {
NO_SYNTAX_THEME,
selectedSyntaxTheme,
syntaxThemeChoices,
syntaxPresetIdentifier,
syntaxThemeFor,
} from '../components/component-detail/syntaxThemeChoices';

describe('the playground syntax theme control', () => {
it('shows an unset optional prop as None, and None sends nothing', () => {
expect(syntaxThemeChoices(false)[0].value).toBe(NO_SYNTAX_THEME);
expect(selectedSyntaxTheme(undefined, false)).toBe(NO_SYNTAX_THEME);
expect(syntaxThemeFor(NO_SYNTAX_THEME)).toBeUndefined();
});

it('offers no None for a required prop, which shows the first preset', () => {
expect(
syntaxThemeChoices(true).some(choice => choice.value === NO_SYNTAX_THEME),
).toBe(false);
expect(selectedSyntaxTheme(undefined, true)).toBe(allSyntaxPresets[0].name);
});

it('shows and sends a chosen preset', () => {
const preset = allSyntaxPresets[1];
expect(selectedSyntaxTheme(preset, false)).toBe(preset.name);
expect(syntaxThemeFor(preset.name)).toBe(preset);
});

it('names a preset by its exported identifier in code', () => {
const dracula = allSyntaxPresets.find(theme => theme.name === 'dracula');
const oneDarkPro = allSyntaxPresets.find(
theme => theme.name === 'one-dark-pro',
);
expect(syntaxPresetIdentifier(dracula)).toBe('dracula');
expect(syntaxPresetIdentifier(oneDarkPro)).toBe('oneDarkPro');
expect(syntaxPresetIdentifier({name: 'dracula'})).toBeNull();
});
});
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import {
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {getComponent, resolveValue} from './resolveElements';
import {syntaxPresetIdentifier} from './syntaxThemeChoices';
import {AppShellMobileContext} from '@astryxdesign/core/AppShell';
import {Button} from '@astryxdesign/core/Button';
import {Card} from '@astryxdesign/core/Card';
Expand Down Expand Up @@ -122,6 +123,10 @@ function formatValue(
if (value === null) {
return 'null';
}
const syntaxPreset = syntaxPresetIdentifier(value);
if (syntaxPreset != null) {
return syntaxPreset;
}
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
if (
value != null &&
typeof value === 'object' &&
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,13 @@ import {Badge} from '@astryxdesign/core/Badge';
import {IconButton} from '@astryxdesign/core/IconButton';
import {Minus, Plus} from 'lucide-react';
import {useMediaQuery} from '@astryxdesign/core/hooks';
import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax';
import {themeObjectsFull} from '../../generated/themeRegistry';
import {coerceEnumOption, type PropControlDescriptor} from './parsePropType';
import {
selectedSyntaxTheme,
syntaxThemeChoices,
syntaxThemeFor,
} from './syntaxThemeChoices';
import {resolveTypeRefs, TypeRefText} from './TypeRefText';
import type {KnobProp} from './InteractivePreview';
import {resolveElementDescriptor} from './resolveElements';
Expand Down Expand Up @@ -166,15 +170,6 @@ const themeOptions = Object.entries(themeObjectsFull).map(
}),
);

const syntaxThemeOptions = allSyntaxPresets.map(theme => ({
value: theme.name,
label: theme.name
.split('-')
.map(part => part.charAt(0).toUpperCase() + part.slice(1))
.join(' '),
theme,
}));

function ThemeControl({
value,
onChange,
Expand Down Expand Up @@ -217,36 +212,20 @@ function ThemeControl({

function SyntaxThemeControl({
value,
isRequired,
onChange,
}: {
value: unknown;
isRequired: boolean;
onChange: (next: unknown) => void;
}) {
const selected =
syntaxThemeOptions.find(
option =>
option.theme === value ||
(value != null &&
typeof value === 'object' &&
'name' in value &&
option.theme.name === value.name),
)?.value ?? syntaxThemeOptions[0].value;

return (
<Selector
label="Syntax theme"
isLabelHidden
value={selected}
options={syntaxThemeOptions.map(({value: optionValue, label}) => ({
value: optionValue,
label,
}))}
onChange={next => {
const match = syntaxThemeOptions.find(option => option.value === next);
if (match) {
onChange(match.theme);
}
}}
value={selectedSyntaxTheme(value, isRequired)}
options={syntaxThemeChoices(isRequired)}
onChange={next => onChange(syntaxThemeFor(next))}
/>
);
}
Expand Down Expand Up @@ -475,7 +454,13 @@ function InlineControl({
case 'theme':
return <ThemeControl value={value} onChange={onChange} />;
case 'syntax-theme':
return <SyntaxThemeControl value={value} onChange={onChange} />;
return (
<SyntaxThemeControl
value={value}
isRequired={!!prop.required}
onChange={onChange}
/>
);
case 'string':
return (
<TextInput
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ export function parsePropType(
if (t === 'DefinedTheme') {
return {kind: 'theme'};
}
if (t === 'SyntaxTheme') {
if (t === 'SyntaxThemeDefinition') {
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
return {kind: 'syntax-theme'};
}
if (t === 'IconType' || t === 'IconName') {
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
* @file syntaxThemeChoices.ts
* @input The value of a syntax-theme prop and whether the prop is required
* @output The preset choices the playground offers, the selected choice, the
* value a choice sends, and the identifier that names a preset in code
* @position Logic of the playground's syntax-theme control
* (PlaygroundPropsTable)
*/

import {allSyntaxPresets} from '@astryxdesign/core/theme/syntax';

/** The choice that leaves an optional syntax-theme prop unset. */
export const NO_SYNTAX_THEME = 'None';

const presets = allSyntaxPresets.map(theme => ({
value: theme.name,
label: theme.name
.split('-')
.map(part => part.charAt(0).toUpperCase() + part.slice(1))
.join(' '),
theme,
}));

/**
* The presets, with a first choice that leaves the prop unset when the prop
* is optional. An unset prop keeps the theme-level syntax colors.
*/
export function syntaxThemeChoices(
isRequired: boolean,
): {value: string; label: string}[] {
const choices = presets.map(({value, label}) => ({value, label}));
return isRequired
? choices
: [{value: NO_SYNTAX_THEME, label: NO_SYNTAX_THEME}, ...choices];
}

/** The choice that shows `value`. */
export function selectedSyntaxTheme(
value: unknown,
isRequired: boolean,
): string {
const match = presets.find(
option =>
option.theme === value ||
(value != null &&
typeof value === 'object' &&
'name' in value &&
option.theme.name === value.name),
);
if (match) {
return match.value;
}
return isRequired ? presets[0].value : NO_SYNTAX_THEME;
}

/**
* The identifier a preset is exported as, such as `oneDarkPro` for
* "one-dark-pro"; null when `value` is not a preset.
*/
export function syntaxPresetIdentifier(value: unknown): string | null {
const match = presets.find(option => option.theme === value);
if (!match) {
return null;
}
return match.value.replace(/-([a-z0-9])/g, (_, next: string) =>
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
next.toUpperCase(),
);
}

/** The value a choice sends: a preset, or nothing for the unset choice. */
export function syntaxThemeFor(choice: string): unknown {
return presets.find(option => option.value === choice)?.theme;
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved
}
3 changes: 2 additions & 1 deletion docs/specs/components/Toast/Toast.spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,8 @@ This table is a review projection; the body below is authoritative.
Toast shows brief, non-modal notifications. This record covers the toast card
(`Toast`), the viewport that stacks, hosts, and announces toasts
(`ToastViewport`, which has no consumer doc of its own), and the behavior the
`useToast` show function drives. Consumer usage lives in `Toast.doc.mjs`.
`useToast` show function drives. Consumer usage lives in `Toast.doc.mjs` (the
card) and `useToast.doc.mjs` (the show function).

## Compatibility and migration

Expand Down
6 changes: 0 additions & 6 deletions packages/cli/test/core-prop-docs.known-drift.json
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,6 @@
"src/TimeInput/TimeInput.doc.mjs TimeInput.controlClassName not_in_doc",
"src/TimeInput/TimeInput.doc.mjs TimeInput.controlStyle not_in_doc",
"src/TimeInput/TimeInput.doc.mjs TimeInput.hasAutoFocus not_in_doc",
"src/Toast/Toast.doc.mjs Toast.autoHideDuration required_mismatch",
"src/Toast/Toast.doc.mjs Toast.collisionBehavior not_in_code",
"src/Toast/Toast.doc.mjs Toast.isAutoHide required_mismatch",
"src/Toast/Toast.doc.mjs Toast.onHide not_in_code",
"src/Toast/Toast.doc.mjs Toast.type required_mismatch",
"src/Toast/Toast.doc.mjs Toast.uniqueID not_in_code",
"src/Tokenizer/Tokenizer.doc.mjs Tokenizer.onKeyDown not_in_doc",
"src/Tooltip/Tooltip.doc.mjs Tooltip.content required_mismatch",
"src/TopNav/TopNavHeading.doc.mjs TopNavHeading.logoLabel not_in_doc",
Expand Down
11 changes: 7 additions & 4 deletions packages/core/src/AlertDialog/useImperativeAlertDialog.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,14 @@ export const docs = {
name: 'useImperativeAlertDialog',
subComponentOf: 'AlertDialog',
displayName: 'useImperativeAlertDialog',
description: 'Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.',
description:
'Hook for showing an alert dialog without managing open state. Call alert.show(options) to open and alert.hide() to close. Render alert.element in your JSX tree.',
props: [
{
name: 'show',
type: '(options: AlertDialogOptions) => void',
description: 'Show the alert dialog with the given options. Options are the same as AlertDialog props minus isOpen/onOpenChange.',
type: "(options: Omit<AlertDialogProps, 'isOpen' | 'onOpenChange'>) => void",
description:
'Show the alert dialog with the given options. Options are the same as AlertDialog props minus isOpen/onOpenChange.',
},
{
name: 'hide',
Expand All @@ -33,7 +35,8 @@ export const docs = {

export const docsDense = {
name: 'useImperativeAlertDialog',
description: 'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.',
description:
'Hook to show alert dialog w/o managing open state. Call alert.show(options) to open, alert.hide() to close; render alert.element in JSX tree.',
propDescriptions: {
show: 'show dialog w/ options; same as AlertDialog props minus isOpen/onOpenChange',
hide: 'hide dialog',
Expand Down
11 changes: 7 additions & 4 deletions packages/core/src/Dialog/useImperativeDialog.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,14 @@ export const docs = {
name: 'useImperativeDialog',
subComponentOf: 'Dialog',
displayName: 'useImperativeDialog',
description: 'Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.',
description:
'Hook for showing a dialog without managing open state. Call dialog.show(content, options) to open and dialog.hide() to close. Render dialog.element in your JSX tree.',
props: [
{
name: 'show',
type: '(content: ReactNode, options?: DialogOptions) => void',
description: 'Show the dialog with the given content. Options are the same as Dialog props minus isOpen/onOpenChange/children.',
type: "(content: ReactNode, options?: Omit<DialogProps, 'isOpen' | 'onOpenChange' | 'children'>) => void",
description:
'Show the dialog with the given content. Options are the same as Dialog props minus isOpen/onOpenChange/children.',
},
{
name: 'hide',
Expand All @@ -33,7 +35,8 @@ export const docs = {

export const docsDense = {
name: 'useImperativeDialog',
description: 'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree',
description:
'hook to show a dialog w/o managing open state; call dialog.show(content, options) to open + dialog.hide() to close; render dialog.element in your JSX tree',
propDescriptions: {
show: 'show the dialog with given content; options = Dialog props minus isOpen/onOpenChange/children',
hide: 'hide the dialog',
Expand Down
2 changes: 1 addition & 1 deletion packages/core/src/Selector/Selector.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -182,7 +182,7 @@ export const docs = {
},
{
name: 'options',
type: 'SelectorOption[]',
type: 'SelectorOptionType[]',
description:
'Array of items: strings, objects with value/label/description/icon/disabled, dividers ({type: "divider"}), or sections ({type: "section", title, options}).',
required: true,
Expand Down
Loading