Skip to content
Draft
Show file tree
Hide file tree
Changes from 7 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 `useToast`'s doc lists the show options and their defaults (`uniqueID`, `collisionBehavior`, `onHide`).
Comment thread
astracat-bot[bot] marked this conversation as resolved.
Resolved

@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 @@ -55,13 +55,7 @@
"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.isExiting not_in_doc",
"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