Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(theme): export the compact definition (AST-012 FR9) (#8301)

Cindy Zhang2763bcc37159
diff --git a/.changeset/theme-compact-definition.md b/.changeset/theme-compact-definition.md
new file mode 100644
index 0000000000..0a1aa071b0
--- /dev/null
+++ b/.changeset/theme-compact-definition.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] `@astryxdesign/core/theme` exports the compact definition: `compactDefinition(widthBreakpoints?)` and `DEFAULT_COMPACT_DEFINITION`. A screen is compact while its viewport is narrower than the theme's `md` point (768 by default) or shorter than 500. The definition carries both edges and ready-made media queries, with and without a coarse pointer, so every component that picks a presentation by screen size reads one shared definition. Nothing changes behavior yet.
+
+@cixzhang
diff --git a/packages/core/src/theme/index.ts b/packages/core/src/theme/index.ts
index ca77a84775..1e0d32f4b7 100644
--- a/packages/core/src/theme/index.ts
+++ b/packages/core/src/theme/index.ts
@@ -49,10 +49,13 @@ export type {
// Ordered environment-conditioned theme adaptations
export {
+ DEFAULT_COMPACT_DEFINITION,
DEFAULT_WIDTH_BREAKPOINTS,
WIDTH_BREAKPOINT_NAMES,
+ compactDefinition,
} from './themeAdaptations';
export type {
+ CompactDefinition,
WidthBreakpointName,
WidthBreakpoints,
ThemeAdaptations,
diff --git a/packages/core/src/theme/themeAdaptations.test.ts b/packages/core/src/theme/themeAdaptations.test.ts
index c1e671c30b..8c71632a20 100644
--- a/packages/core/src/theme/themeAdaptations.test.ts
+++ b/packages/core/src/theme/themeAdaptations.test.ts
@@ -9,8 +9,10 @@
import {describe, expect, it} from 'vitest';
import {
+ DEFAULT_COMPACT_DEFINITION,
DEFAULT_WIDTH_BREAKPOINTS,
WIDTH_BREAKPOINT_NAMES,
+ compactDefinition,
defineTheme,
generateAdaptationCSS,
generateThemeCSS,
@@ -103,6 +105,41 @@ describe('width breakpoint metadata', () => {
});
});
+describe('compact definition (spec:AST-012 FR9)', () => {
+ it('is width below md or height below 500 at the default points', () => {
+ expect(DEFAULT_COMPACT_DEFINITION).toEqual({
+ widthBelow: 768,
+ heightBelow: 500,
+ query: '(width < 768px), (height < 500px)',
+ coarsePointerQuery:
+ '(width < 768px) and (pointer: coarse), (height < 500px) and (pointer: coarse)',
+ });
+ expect(compactDefinition()).toEqual(DEFAULT_COMPACT_DEFINITION);
+ });
+
+ it("follows a theme's effective md point and keeps the height edge", () => {
+ const theme = defineTheme({
+ name: 'wide-md',
+ adaptations: {widthBreakpoints: {md: 800, lg: 1100}},
+ });
+ const points = theme.__adaptations?.widthBreakpoints;
+ if (points == null) {
+ throw new Error('theme has no effective width breakpoints');
+ }
+ expect(compactDefinition(points)).toEqual({
+ widthBelow: 800,
+ heightBelow: 500,
+ query: '(width < 800px), (height < 500px)',
+ coarsePointerQuery:
+ '(width < 800px) and (pointer: coarse), (height < 500px) and (pointer: coarse)',
+ });
+ });
+
+ it('is frozen, so no caller can change the shared definition', () => {
+ expect(Object.isFrozen(DEFAULT_COMPACT_DEFINITION)).toBe(true);
+ });
+});
+
describe('closed conditions and media queries', () => {
it('lowers inclusive from and exclusive below edges', () => {
const theme = defineTheme(
diff --git a/packages/core/src/theme/themeAdaptations.ts b/packages/core/src/theme/themeAdaptations.ts
index 9e43095154..6abc4384bc 100644
--- a/packages/core/src/theme/themeAdaptations.ts
+++ b/packages/core/src/theme/themeAdaptations.ts
@@ -3,7 +3,8 @@
/**
* @file themeAdaptations.ts
* @input Ordered environment-conditioned theme value rules from defineTheme
- * @output Validated breakpoint metadata and resolved CSS-first rule layers
+ * @output Validated breakpoint metadata, the compact definition, and resolved
+ * CSS-first rule layers
* @position Theme system core; consumed by defineTheme, AppShell, and the CSS compiler
*
* Adaptations are deliberately closed and ordered. Width points are fixed names,
@@ -54,6 +55,47 @@ export const DEFAULT_WIDTH_BREAKPOINTS: Readonly<WidthBreakpoints> =
'2xl': 1536,
});
+/**
+ * When a screen is compact, for a component that chooses a presentation by
+ * screen size (`spec:AST-012` FR9): width below the theme's effective `md`
+ * point, or height below 500. The numbers are the same on every platform (CSS
+ * pixels on the web, points on iOS, density-independent pixels on Android).
+ */
+export interface CompactDefinition {
+ /** Compact below this viewport width: the effective `md` point. */
+ readonly widthBelow: number;
+ /** Compact below this viewport height. */
+ readonly heightBelow: number;
+ /** The definition as a media query list, without the `@media` keyword. */
+ readonly query: string;
+ /** Compact and a coarse primary pointer, without the `@media` keyword. */
+ readonly coarsePointerQuery: string;
+}
+
+/** The viewport height below which a screen is compact (`spec:AST-012` FR9). */
+const COMPACT_HEIGHT_BELOW = 500;
+
+/**
+ * The compact definition for a theme's width points (`spec:AST-012` FR9).
+ * Pass a theme's effective width breakpoints; omit them for the defaults.
+ */
+export function compactDefinition(
+ points: Readonly<Pick<WidthBreakpoints, 'md'>> = DEFAULT_WIDTH_BREAKPOINTS,
+): CompactDefinition {
+ const width = `(width < ${points.md}px)`;
+ const height = `(height < ${COMPACT_HEIGHT_BELOW}px)`;
+ return Object.freeze({
+ widthBelow: points.md,
+ heightBelow: COMPACT_HEIGHT_BELOW,
+ query: `${width}, ${height}`,
+ coarsePointerQuery: `${width} and (pointer: coarse), ${height} and (pointer: coarse)`,
+ });
+}
+
+/** The compact definition at the default width points. */
+export const DEFAULT_COMPACT_DEFINITION: CompactDefinition =
+ compactDefinition();
+
/** Inclusive lower and exclusive upper edges for one width condition. */
export interface ThemeAdaptationWidthCondition {
/** Match at and above this named point. */