@a-type/ui 5.0.22 → 6.0.0

package/src/arbor/arbor.ts

@@ -0,0 +1,348 @@
+import { css, definePreset } from '@arbor-css/core';
+import {
+	ArborPresetConfig,
+	compileSingleColor,
+	presetArbor,
+} from '@arbor-css/core/preset-arbor';
+import { $userColorHue, $userColorSaturation } from './props.js';
+
+const defaultColors = {
+	ranges: {
+		lemon: {
+			hue: 86,
+		},
+		leek: {
+			hue: 165.88,
+		},
+		tomato: {
+			hue: 10.51,
+		},
+		blueberry: {
+			hue: 248.14,
+		},
+		eggplant: {
+			hue: 280.21,
+		},
+		attention: {
+			hue: 30,
+		},
+		success: {
+			hue: 140,
+		},
+		user: {
+			hue: 0,
+		},
+	},
+	mainColor: 'lemon',
+};
+
+export type DefaultColorRangeName = keyof typeof defaultColors.ranges;
+
+export type ATypeConfig<
+	TColors extends DefaultColorRangeName = DefaultColorRangeName,
+> = ArborPresetConfig<TColors> & {
+	roundActions?: boolean;
+	roundControls?: boolean;
+};
+
+export function presetAtype<
+	TColors extends DefaultColorRangeName = DefaultColorRangeName,
+>(config?: ATypeConfig<TColors>) {
+	const base = presetArbor({
+		...config,
+		color: {
+			...config?.color,
+			ranges: {
+				...defaultColors.ranges,
+				...config?.color?.ranges,
+			},
+			mainColor: config?.color?.mainColor || defaultColors.mainColor,
+			globalSaturation: 0.5,
+		},
+		typography: {
+			defaultFontSize: '16px',
+			minFontSize: '12px',
+			minWeight: 200,
+			maxWeight: 600,
+			weightStep: 100,
+			baseWeight: 400,
+			lineHeightStep: 0.125,
+			minLineHeight: 1,
+			...config?.typography,
+		},
+		spacing: {
+			baseSize: '8px',
+		},
+		shape: {
+			roundness: 1,
+		},
+		shadow: {
+			defaultColor: 'rgba(0, 0, 0, 0.05)',
+		},
+	});
+
+	const preset = definePreset({
+		name: 'a-type',
+		extends: [base],
+		baseMode: ($) => ({
+			color: {
+				accent: $.mode.color.palette.leek,
+			},
+			action: {
+				roundness: config?.roundActions === false ? undefined : 99,
+
+				light: {
+					bg: $.mode.color.main.light,
+					fg: $.mode.global.trueHeavyColor,
+					border: css`
+						${$.mode.action.light.borderWidth} ${$.mode.action.light
+							.borderStyle} ${$.mode.action.light.borderColor}
+					`,
+					borderColor: $.mixins.fg.ref,
+					borderStyle: 'solid',
+					borderWidth: '1px',
+				},
+				primary: {
+					borderColor: $.mixins.fg.ref,
+				},
+				secondary: {
+					borderColor: $.mixins.fg.ref,
+				},
+			},
+			control: {
+				roundness: config?.roundControls ? 1.5 : undefined,
+				padding: {
+					block: $.mode.spacing.sm,
+				},
+			},
+			surface: {
+				roundness: 1,
+			},
+			user: {
+				hue: 0,
+				saturation: 1,
+			},
+			primitive: {
+				color: {
+					user: compileSingleColor(
+						{
+							hue: $.mode.user.hue,
+							saturation: $.mode.user.saturation,
+						},
+						$.mode.global,
+					),
+				},
+			},
+		}),
+		modeSchema: {
+			color: {
+				accent: base.modeSchema.color.main,
+			},
+			user: {
+				hue: {
+					purpose: 'other',
+					description: 'A user-input hue value',
+				},
+				saturation: {
+					purpose: 'scalar',
+					description: 'A user-input saturation value between 0 and 1',
+				},
+			},
+			action: {
+				light: base.modeSchema.action.primary,
+			},
+		},
+		mixins: (create, $) => {
+			return {
+				actionLight: create('action-light', {
+					definition: (css) => css`
+						${base.mixins.bg.apply({ '--color': $.mode.action.light.bg })}
+						${base.mixins.fg.apply({ '--color': $.mode.action.light.fg })}
+						${base.mixins.borderColor.apply({
+							'--color': $.mode.action.light.borderColor,
+						})}
+						border-width: ${$.mode.action.light.borderWidth};
+						border-style: ${$.mode.action.light.borderStyle};
+						border-radius: ${$.mode.action.radius};
+						padding: ${$.mode.action.padding.$root};
+					`,
+				}),
+				hover: create('hover', {
+					definition: (css) => css`
+						&:hover {
+							${base.mixins.bgHeavier.apply({ '--step': 1 })}
+							${base.mixins.ring.apply({
+								'--ring': base.functions.ring.compute({
+									'--color': $.mixins.bg.ref,
+									'--size': '4px',
+								}),
+							})}
+
+							&[data-emphasis="primary"] {
+								${base.mixins.bgLighter.apply({ '--step': 1 })}
+							}
+						}
+					`,
+				}),
+				focus: create('focus', {
+					definition: (css) => css`
+						&:focus {
+							outline: none;
+						}
+						&:focus-visible,
+						&[data-focus-visible='true'] {
+							${base.mixins.bgLighter.apply({ '--step': 1 })}
+							${base.mixins.ring.apply({
+								'--ring': base.functions.ring.compute({
+									'--color': $.mode.color.main.heavy,
+									'--size': '2px',
+								}),
+							})}
+
+							&[data-emphasis="primary"] {
+								${base.mixins.bgLighter.apply({ '--step': 2 })}
+							}
+						}
+					`,
+				}),
+				active: create('active', {
+					definition: (css) => css`
+						&:active {
+							${base.mixins.bgHeavier.apply({ '--step': 2 })}
+
+							&[data-emphasis="primary"] {
+								${base.mixins.bgLighter.apply({ '--step': 2 })}
+							}
+						}
+					`,
+				}),
+				disabled: create('disabled', {
+					definition: (css) => css`
+						&&:disabled,
+						&&[data-disabled='true'] {
+							cursor: default;
+							box-shadow: none;
+							${base.mixins.bgDesaturated.apply({ '--step': 8 })}
+							${base.mixins.fgFaded.apply({
+								'--opacity': 0.65,
+								'--source': $.mode.color.neutral.ink,
+							})}
+						}
+					`,
+				}),
+			};
+		},
+		functions: (create, $) => ({
+			focusRing: create('focus-ring', {
+				parameters: [
+					{
+						name: '--width',
+						fallback: '2px',
+					},
+				],
+				definition: (css, width) =>
+					css`0 0 0 ${width} ${$.mode.color.main.heavy}`,
+			}),
+		}),
+	});
+
+	preset.bundleMode('accent', {
+		color: {
+			main: preset.$.mode.color.accent,
+		},
+	});
+	preset.bundleMode('success', {
+		color: {
+			main: preset.$.mode.color.palette.success,
+		},
+	});
+	preset.bundleMode('attention', {
+		color: {
+			main: preset.$.mode.color.palette.attention,
+		},
+	});
+	preset.bundleMode('neutral', {
+		color: {
+			main: preset.$.mode.color.neutral,
+		},
+	});
+	preset.bundleMode('user', {
+		user: {
+			hue: `var(${$userColorHue}, 200)`,
+			saturation: `var(${$userColorSaturation}, 1)`,
+		},
+		color: {
+			main: preset.$.mode.color.palette.user,
+		},
+	});
+
+	const allColorNames = new Set<DefaultColorRangeName>([
+		...(Object.keys(defaultColors.ranges) as DefaultColorRangeName[]),
+		...(config?.color?.ranges
+			? (Object.keys(config.color.ranges) as DefaultColorRangeName[])
+			: []),
+	]);
+	for (const colorName of allColorNames) {
+		preset.bundleMode(colorName, {
+			color: {
+				main: preset.$.mode.color.palette[colorName],
+				// avoid assigning leek to both main and accent
+				accent:
+					colorName === 'leek' ? preset.$.mode.color.palette.lemon : undefined,
+			},
+		});
+	}
+
+	// density and size
+	preset.bundleMode('dense', {
+		global: {
+			spacing: {
+				density: 1.25,
+			},
+			typography: {
+				size: 0.825,
+			},
+		},
+	});
+	preset.bundleMode('denser', {
+		global: {
+			spacing: {
+				density: 1.5,
+			},
+			typography: {
+				minFontSize: '10px',
+				size: 0.75,
+			},
+		},
+	});
+	preset.bundleMode('density-reset', {
+		global: {
+			spacing: {
+				density: 1,
+			},
+		},
+	});
+
+	preset.bundleMode('heading', {
+		global: {
+			typography: {
+				size: 1.5,
+			},
+		},
+	});
+	preset.bundleMode('hero', {
+		global: {
+			typography: {
+				size: 3,
+				fontSizeScaleBase: 1.5,
+			},
+			spacing: {
+				density: 0.5,
+			},
+		},
+	});
+
+	return preset;
+}
+
+export default presetAtype;

package/src/arbor/props.ts

@@ -0,0 +1,2 @@
+export const $userColorHue = '--🖌️-hue';
+export const $userColorSaturation = '--🖌️-saturation';

package/src/behaviors/iconOnly.module.css

@@ -0,0 +1,4 @@
+.iconWrapper {
+	display: inline-block;
+	flex-shrink: 0;
+}

package/src/behaviors/iconOnly.ts

@@ -0,0 +1,214 @@
+/**
+ * Encapsulates tools for achieving an "icon only" automatic behavior for controls and other
+ * components which support icons alongside text.
+ *
+ * Often in designs, we want to modify the padding or shape of a component when it is only
+ * housing a single icon.
+ *
+ * We also want to audit the labeling of icon-only elements when used by developers to ensure
+ * they are providing an accessible aria-label for screen readers.
+ */
+
+import { useRender, UseRenderComponentProps } from '@base-ui/react';
+import { clsx } from 'clsx';
+import {
+	Children,
+	forwardRef,
+	Fragment,
+	ReactNode,
+	useCallback,
+	useLayoutEffect,
+	useRef,
+} from 'react';
+import { Icon } from '../components/icon/Icon.js';
+import useMergedRef from '../hooks/useMergedRef.js';
+import cls from './iconOnly.module.css';
+
+/**
+ * Assigns data attributes to an element outside React's render flow
+ * based on whether we detect icon or label content within the element.
+ * This hook does NOT re-render your component when it updates detected
+ * content - use CSS selectors on the data attributes to apply styling
+ * customizations instead.
+ *
+ * Attributes applied:
+ * - `data-icon-only`: "true" if at least one child element is detected as an icon and no text content is detected, otherwise "false"
+ * - `data-has-icon`: "true" if at least one child element is detected as an icon, otherwise "false"
+ * - `data-has-label`: "true" if any text content is detected, otherwise "false"
+ * - `data-icon-count`: the number of child elements detected as icons
+ *
+ */
+export function useIconOnlyDataAttributes(
+	/**
+	 * Pass the component's children to preload icon attributes before initial render, too.
+	 * This is not as foolproof as the post-render DOM inspection but is important for avoiding
+	 * flashes of inconsistency in the majority of use cases.
+	 */
+	children: ReactNode | undefined,
+): {
+	ref: React.Ref<HTMLElement>;
+	props: any;
+	info: {
+		hasIconOnly: boolean;
+		hasIcon: boolean;
+		hasLabel: boolean;
+		iconCount: number;
+	};
+} {
+	const nodeRef = useRef<HTMLElement | null>(null);
+	const ref = useCallback((node: HTMLElement | null) => {
+		if (node) {
+			applyPartAttributesAndAuditLabelUsage(node);
+		}
+	}, []);
+
+	useLayoutEffect(() => {
+		const node = nodeRef.current;
+		if (node) {
+			const mutationObserver = new MutationObserver((entries) => {
+				applyPartAttributesAndAuditLabelUsage(entries[0].target as HTMLElement);
+			});
+			mutationObserver.observe(node, { childList: true, subtree: true });
+			return () => mutationObserver.disconnect();
+		}
+	}, []);
+
+	const preloadedDataAttributes = getPreloadedIconOnlyDataAttributes(children);
+
+	const finalRef = useMergedRef(nodeRef, ref);
+	return {
+		ref: finalRef,
+		props: preloadedDataAttributes,
+		info: {
+			hasIconOnly: preloadedDataAttributes['data-icon-only'] === 'true',
+			hasIcon: preloadedDataAttributes['data-has-icon'] === 'true',
+			hasLabel: preloadedDataAttributes['data-has-label'] === 'true',
+			iconCount: Number(preloadedDataAttributes['data-icon-count']),
+		},
+	};
+}
+
+function applyPartAttributesAndAuditLabelUsage(rootElement: HTMLElement) {
+	// each child node that's not an icon counts as a label
+	const registry = {
+		icon: 0,
+		label: 0,
+	};
+	rootElement.childNodes.forEach((child) => {
+		if (!(child instanceof HTMLElement || child instanceof SVGElement)) {
+			return;
+		}
+		if (child.style.display === 'none' || child.style.width === '0') {
+			// skip hidden elements
+			return;
+		}
+		if (child instanceof HTMLElement || child instanceof SVGElement) {
+			// best effort heuristic to detect icons we use:
+			// - our Flow Icon and the IconWrapper component below both data-icon=true, most reliable
+			// - AntD's Icon component has a class of "anticon" (potentially breakable)
+			// - General heuristic "icon" class
+			if (
+				child.dataset.icon === 'true' ||
+				child.classList.contains('anticon') ||
+				child.classList.contains('icon')
+			) {
+				registry.icon++;
+			}
+		}
+	});
+	if (rootElement.textContent) {
+		registry.label++;
+	}
+	rootElement.setAttribute('data-has-icon', String(registry.icon > 0));
+	rootElement.setAttribute('data-has-label', String(registry.label > 0));
+	rootElement.setAttribute('data-icon-count', String(registry.icon));
+	rootElement.setAttribute(
+		'data-icon-only',
+		String(registry.icon > 0 && registry.label === 0),
+	);
+
+	// audit usage of icon-only and log a warning if aria-label is not provided
+	const hasAccessibleLabel =
+		rootElement.getAttribute('aria-label') ||
+		rootElement.getAttribute('aria-labelledby');
+	if (registry.icon > 0 && registry.label === 0 && !hasAccessibleLabel) {
+		console.warn(
+			'An element with icon-only content is missing an aria-label for screen readers. Please add an aria-label to this element to ensure it is accessible.',
+			rootElement,
+		);
+	}
+}
+
+/**
+ * Does a best-effort attempt to determine icon-only status of a component by inspecting
+ * React children. This is less robust than the post-render inspection of the DOM done later,
+ * but can help avoid flashes of inconsistent styling in nearly all cases.
+ */
+function getPreloadedIconOnlyDataAttributes(children: ReactNode) {
+	const childrenUnwrapped = unwrapChildFragments(children);
+	const icons = childrenUnwrapped.filter(isIconReactChild);
+	const hasIcon = icons.length > 0;
+	// assume non-icons are labels - we don't need a label count, so there's not much point in
+	// trying to be clever here anyways.
+	const hasLabel = childrenUnwrapped.length > icons.length;
+	return {
+		'data-has-icon': String(hasIcon),
+		'data-has-label': String(hasLabel),
+		'data-icon-count': String(icons.length),
+		'data-icon-only': String(hasIcon && !hasLabel),
+	};
+}
+
+function isIconReactChild(node: ReactNode) {
+	if (typeof node !== 'object' || node === null) {
+		return false;
+	}
+	if ('type' in node) {
+		const type = node.type;
+		return (
+			type === IconWrapper ||
+			type === Icon ||
+			(node.props as any)?.['data-icon']
+		);
+	}
+
+	return false;
+}
+
+export interface IconWrapperProps extends UseRenderComponentProps<'div'> {}
+/**
+ * A reusable sub-component which tags arbitrary content as an "icon" for the purposes of `useIconOnlyDataAttributes`.
+ * Attach it to your main component's sub-component set so that users can supply custom content which
+ * behaves as an icon and triggers the appropriate "icon only" styles when necessary.
+ */
+export const IconWrapper = forwardRef<HTMLDivElement, IconWrapperProps>(
+	function IconWrapper({ className, render, ...props }, ref) {
+		return useRender({
+			defaultTagName: 'div',
+			render,
+			ref,
+			props: {
+				'data-icon': true,
+				className: clsx(cls.iconWrapper, className),
+				...props,
+			},
+		});
+	},
+);
+
+function unwrapChildFragments(children: ReactNode): ReactNode[] {
+	const unwrapped: ReactNode[] = [];
+	Children.forEach(children, (child) => {
+		if (
+			child &&
+			typeof child === 'object' &&
+			'type' in child &&
+			child.type === Fragment
+		) {
+			unwrapped.push(...unwrapChildFragments((child.props as any).children));
+		} else {
+			unwrapped.push(child);
+		}
+	});
+	return unwrapped;
+}

package/src/colors.module.css

@@ -0,0 +1,59 @@
+.bgWash {
+	@apply --mx-bg(var(--m-color-main-wash));
+}
+.bgLight {
+	@apply --mx-bg(var(--m-color-main-light));
+}
+.bgMid {
+	@apply --mx-bg(var(--m-color-main));
+}
+.bgHeavy {
+	@apply --mx-bg(var(--m-color-main-heavy));
+}
+.bgInk {
+	@apply --mx-bg(var(--m-color-main-ink));
+}
+
+.bgNeutralInk {
+	@apply --mx-bg(var(--m-color-neutral-ink));
+}
+.bgNeutralPaper {
+	@apply --mx-bg(var(--m-color-neutral-paper));
+}
+.bgNeutralWash {
+	@apply --mx-bg(var(--m-color-neutral-wash));
+}
+
+.rangeLabel {
+	position: absolute;
+	left: 0;
+	top: 0;
+	@apply --mx-fg(var(--m-color-neutral));
+	@apply --mx-bg(var(--m-color-neutral-ink));
+	@apply --mx-bg-faded(50%);
+	font-size: var(--m-text-ambient-size);
+	line-height: var(--m-text-ambient-lineHeight);
+	font-weight: var(--m-text-ambient-weight);
+	padding: var(--m-spacing-xs);
+	border-radius: var(--m-radius-sm);
+}
+
+.bgLighten1 {
+	@apply --mx-bg-lighter(1);
+}
+.bgLighten2 {
+	@apply --mx-bg-lighter(2);
+}
+.bgDarken1 {
+	@apply --mx-bg-heavier(1);
+}
+.bgDarken2 {
+	@apply --mx-bg-heavier(2);
+}
+
+.bgBetweenMidLight {
+	@apply --mx-bg(--fn-color-between(var(--m-color-main), var(--m-color-main-light)));
+}
+.bgBetweenMidHeavy {
+	@apply --mx-bg(--fn-color-between(var(--m-color-main), var(--m-color-main-heavy)));
+}

package/src/colors.snapshots.tsx

@@ -3,6 +3,8 @@ import { render } from './__tests__/render.js';
 import { Default } from './colors.stories.js';
 
 it('colors match snapshot', async () => {
-	const result = render(Default.render?.({}, {} as any));
+	const result = render(
+		Default.render?.({}, {} as any) ?? <div>Failed to render</div>,
+	);
 	await expect(result.baseElement).toMatchScreenshot('snapshot');
 });