@astryxdesign/core 0.7.0 → 0.7.1-canary.0365e23

package/src/theme/syntax/defineSyntaxTheme.ts

@@ -11,7 +11,11 @@
  * @see https://github.com/facebook/astryx/issues/1148
  */
 
-import {syntaxTokenDefaults, type SyntaxTokenName} from './tokens';
+import {
+  syntaxTokenDefaults,
+  DIFF_SYNTAX_TOKEN_NAMES,
+  type SyntaxTokenName,
+} from './tokens';
 import {devWarn} from '../../utils/devWarning';
 
 // =============================================================================
@@ -33,7 +37,12 @@ export type SyntaxThemeTokenKey =
   | 'attribute'
   | 'property'
   | 'punctuation'
-  | 'background';
+  | 'background'
+  | DiffSyntaxThemeTokenKey;
+
+/** The diff row slots a syntax theme MAY set; unset ones keep their defaults. */
+export type DiffSyntaxThemeTokenKey =
+  'added' | 'removed' | 'diff-header' | 'added-marker' | 'removed-marker';
 
 /**
  * Token value — either a single string or a [light, dark] tuple.
@@ -41,14 +50,28 @@ export type SyntaxThemeTokenKey =
  */
 export type SyntaxTokenValue = string | [light: string, dark: string];
 
-/** Token map for defineSyntaxTheme input — values can be strings or tuples. */
+/**
+ * Token map for defineSyntaxTheme input — values can be strings or tuples.
+ * The diff row slots are optional: a theme that sets none keeps the defaults
+ * (semantic success/error muted tints and the muted surface).
+ */
 export type SyntaxThemeTokenInput = Record<
-  SyntaxThemeTokenKey,
+  Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,
   SyntaxTokenValue
->;
+> &
+  Partial<Record<DiffSyntaxThemeTokenKey, SyntaxTokenValue>>;
 
-/** Resolved token map — all values are CSS strings (tuples resolved to light-dark()). */
-export type SyntaxThemeTokenMap = Record<SyntaxThemeTokenKey, string>;
+/**
+ * Resolved token map — all values are CSS strings (tuples resolved to
+ * light-dark()). The diff row slots are optional here as in the input, so a
+ * map written before they existed still type-checks; an unset slot renders
+ * its default.
+ */
+export type SyntaxThemeTokenMap = Record<
+  Exclude<SyntaxThemeTokenKey, DiffSyntaxThemeTokenKey>,
+  string
+> &
+  Partial<Record<DiffSyntaxThemeTokenKey, string>>;
 
 /** Input to defineSyntaxTheme. */
 export interface SyntaxThemeInput {
@@ -81,6 +104,22 @@ export const ALL_SYNTAX_KEYS: SyntaxThemeTokenKey[] = Object.keys(
   syntaxTokenDefaults,
 ).map(k => k.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey);
 
+const DIFF_KEYS = new Set<SyntaxThemeTokenKey>(
+  DIFF_SYNTAX_TOKEN_NAMES.map(
+    name => name.replace(CSS_PREFIX, '') as SyntaxThemeTokenKey,
+  ),
+);
+
+/** The marker slots: unset in a theme, they follow that theme's punctuation. */
+const MARKER_KEYS = new Set<SyntaxThemeTokenKey>([
+  'added-marker',
+  'removed-marker',
+]);
+
+/** The keys every syntax theme must set: everything but the diff rows. */
+export const REQUIRED_SYNTAX_KEYS: SyntaxThemeTokenKey[] =
+  ALL_SYNTAX_KEYS.filter(key => !DIFF_KEYS.has(key));
+
 // =============================================================================
 // Helpers
 // =============================================================================
@@ -138,19 +177,37 @@ export function resolveSyntaxTokenForMode(
 export function defineSyntaxTheme(
   input: SyntaxThemeInput,
 ): SyntaxThemeDefinition {
-  const missing = ALL_SYNTAX_KEYS.filter(key => !(key in input.tokens));
+  const missing = REQUIRED_SYNTAX_KEYS.filter(key => !(key in input.tokens));
   if (missing.length > 0) {
     devWarn(
       'defineSyntaxTheme',
       `"${input.name}": missing tokens: ${missing.join(', ')}. ` +
-        `All 14 syntax tokens are required.`,
+        `All ${REQUIRED_SYNTAX_KEYS.length} syntax colour tokens are required; ` +
+        `the diff row slots (added, removed, diff-header, added-marker, removed-marker) are optional.`,
     );
   }
 
-  // Resolve tuples to light-dark() CSS strings
+  // Resolve tuples to light-dark() CSS strings. An unset diff row paint keeps
+  // its default so every existing theme renders a readable diff unchanged; an
+  // unset marker slot takes this theme's own line-number colour (its
+  // punctuation token) rather than the page theme's green and red, and an
+  // unset header paint is none at all (the header row sits on this theme's
+  // own background with punctuation text), so number, glyph, and header
+  // text stay legible on this theme's background in every page mode — the
+  // glyph's shape carries the meaning where the colour does not.
   const resolved: Partial<SyntaxThemeTokenMap> = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    resolved[key] = resolveTokenValue(input.tokens[key]);
+    const value = (
+      input.tokens as Partial<Record<SyntaxThemeTokenKey, SyntaxTokenValue>>
+    )[key];
+    resolved[key] =
+      value !== undefined
+        ? resolveTokenValue(value)
+        : MARKER_KEYS.has(key)
+          ? 'var(--color-syntax-punctuation)'
+          : key === 'diff-header'
+            ? 'transparent'
+            : syntaxTokenDefaults[toCSSProperty(key)];
   }
 
   return {
@@ -170,14 +227,17 @@ export function syntaxThemeStyle(
 ): Record<string, string> {
   const vars: Record<string, string> = {};
   for (const key of ALL_SYNTAX_KEYS) {
-    vars[toCSSProperty(key)] = theme.tokens[key];
+    // An unset diff slot is left to its default rather than written empty.
+    const value = theme.tokens[key];
+    if (value !== undefined) vars[toCSSProperty(key)] = value;
   }
   return vars;
 }
 
 /** Convert a syntax theme to CSS declarations (no selector wrapper). */
 export function syntaxThemeToCSS(theme: SyntaxThemeDefinition): string {
-  return ALL_SYNTAX_KEYS.map(
-    key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';',
-  ).join('\n  ');
+  // An unset diff slot is left to its default rather than written `undefined`.
+  return ALL_SYNTAX_KEYS.filter(key => theme.tokens[key] !== undefined)
+    .map(key => toCSSProperty(key) + ': ' + theme.tokens[key] + ';')
+    .join('\n  ');
 }

package/src/theme/syntax/index.ts

@@ -14,7 +14,11 @@
 export {syntaxTokenDefaults} from './tokens';
 export type {SyntaxTokenName} from './tokens';
 
-export {defineSyntaxTheme, syntaxThemeStyle, syntaxThemeToCSS} from './defineSyntaxTheme';
+export {
+  defineSyntaxTheme,
+  syntaxThemeStyle,
+  syntaxThemeToCSS,
+} from './defineSyntaxTheme';
 export type {
   SyntaxThemeDefinition,
   SyntaxThemeInput,

package/src/theme/syntax/tokens.ts

@@ -13,8 +13,11 @@
  * colors automatically adapt to any theme's color system. Themes can also
  * set an explicit syntax theme via defineTheme({ syntax: dracula }).
  *
- * 14-token architecture validated against 11 community code themes.
- * All themes map cleanly to these 14 slots.
+ * 14 token colours and the code background, validated against 11 community
+ * code themes — all of them map cleanly to those slots — plus five diff row
+ * slots (added, removed, header paints; added and removed markers) that default
+ * to semantic tokens, so a syntax theme that does not set them keeps a
+ * readable diff.
  *
  * @see https://github.com/facebook/astryx/issues/1148
  */
@@ -51,6 +54,33 @@ export const syntaxTokenDefaults = {
   '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
   '--color-syntax-background': 'var(--color-background-muted)',
+  // Diff rows (CodeBlock isDiff): whole-row tints behind unchanged syntax
+  // colours. Added/removed derive from the semantic success/error muted
+  // tokens at 25% strength: at full strength the secondary-grey syntax
+  // tokens (operator, punctuation, comment) fall under 4.5:1 on the tints
+  // in light; at 25% every default token clears it on both schemes with
+  // margin while the tint still reads against the plain row. Header rows
+  // (@@, and ---/+++ before the first hunk) sit on the muted surface.
+  '--color-syntax-added':
+    'color-mix(in srgb, var(--color-success-muted) 25%, transparent)',
+  '--color-syntax-removed':
+    'color-mix(in srgb, var(--color-error-muted) 25%, transparent)',
+  '--color-syntax-diff-header': 'var(--color-background-muted)',
+  // The margin of a changed row — its line number and +/- glyph — in the
+  // default theme's tinted-text tokens, made for tinted surfaces; a defined
+  // syntax theme that leaves them unset follows its own punctuation colour
+  // (see defineSyntaxTheme). Code text keeps the syntax theme's colours.
+  '--color-syntax-added-marker': 'var(--color-text-green)',
+  '--color-syntax-removed-marker': 'var(--color-text-red)',
 } as const;
 
 export type SyntaxTokenName = keyof typeof syntaxTokenDefaults;
+
+/** The five diff row slots: optional in a syntax theme, defaulted when unset. */
+export const DIFF_SYNTAX_TOKEN_NAMES = [
+  '--color-syntax-added',
+  '--color-syntax-removed',
+  '--color-syntax-diff-header',
+  '--color-syntax-added-marker',
+  '--color-syntax-removed-marker',
+] as const satisfies ReadonlyArray<SyntaxTokenName>;

package/src/theme/syntax/useSyntaxTheme.diff.test.tsx

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useSyntaxTheme.diff.test.tsx
+ * @input A SyntaxTheme provider with a preset that sets no diff slots
+ * @output The hook hands a canvas consumer paintable colours for every slot
+ * @position Diff slot resolution for the imperative (canvas) path
+ */
+
+import {render} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {SyntaxTheme, useSyntaxTheme} from './SyntaxTheme';
+import {dracula} from './presets';
+import {parseColor} from '../../utils/color';
+
+function Probe({onTokens}: {onTokens: (t: Record<string, string>) => void}) {
+  const syntax = useSyntaxTheme();
+  if (syntax) onTokens(syntax.tokens);
+  return null;
+}
+
+describe('useSyntaxTheme diff slots', () => {
+  it("resolves unset marker slots to the theme's own punctuation colour", () => {
+    let tokens: Record<string, string> = {};
+    render(
+      <SyntaxTheme theme={dracula}>
+        <Probe onTokens={t => (tokens = t)} />
+      </SyntaxTheme>,
+    );
+    expect(tokens.punctuation).toMatch(/^#|^rgb/);
+    expect(tokens['added-marker']).toBe(tokens.punctuation);
+    expect(tokens['removed-marker']).toBe(tokens.punctuation);
+    // The row paints derive from the page theme's resolved muted tokens at
+    // the default strength, as rgba() a canvas can paint.
+    expect(tokens.added).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);
+    expect(tokens.removed).toMatch(/^rgba\(\d+, \d+, \d+, 0\.\d+\)$/);
+    expect(parseColor(tokens.added)?.a).toBeCloseTo(0.2 * 0.25, 3);
+    expect(tokens['diff-header']).toBe('transparent');
+  });
+});

package/src/utils/focusReturn.test.ts

@@ -1,7 +1,11 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, afterEach} from 'vitest';
-import {isFocusDetached} from './focusReturn';
+import {describe, it, expect, afterEach, beforeEach, vi} from 'vitest';
+import {focusForLastInput, isFocusDetached} from './focusReturn';
+import {
+  __resetInteractionModalityForTest,
+  __startInteractionModalityTrackingForTest,
+} from './interactionModality';
 
 describe('isFocusDetached', () => {
   afterEach(() => {
@@ -40,3 +44,76 @@ describe('isFocusDetached', () => {
     expect(isFocusDetached(doc)).toBe(true);
   });
 });
+
+describe('focusForLastInput', () => {
+  beforeEach(() => {
+    __startInteractionModalityTrackingForTest();
+    __resetInteractionModalityForTest();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    document.body.innerHTML = '';
+  });
+
+  function button(): HTMLButtonElement {
+    const element = document.createElement('button');
+    document.body.appendChild(element);
+    return element;
+  }
+
+  it('leaves the ring to the browser after keyboard input, passing the options through', () => {
+    const element = button();
+    const focus = vi.spyOn(element, 'focus');
+    focusForLastInput(element);
+    focusForLastInput(element, {preventScroll: true});
+    expect(focus.mock.calls).toEqual([[], [{preventScroll: true}]]);
+  });
+
+  it('asks the browser for no ring after pointer input, keeping the options', () => {
+    const element = button();
+    document.dispatchEvent(new Event('pointerdown'));
+    const focus = vi.spyOn(element, 'focus');
+    focusForLastInput(element);
+    focusForLastInput(element, {preventScroll: true});
+    expect(focus.mock.calls).toEqual([
+      [{focusVisible: false}],
+      [{preventScroll: true, focusVisible: false}],
+    ]);
+  });
+
+  it('keeps plain focus on a text field after pointer input', () => {
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+    document.dispatchEvent(new Event('pointerdown'));
+    const focus = vi.spyOn(input, 'focus');
+    focusForLastInput(input, {preventScroll: true});
+    expect(focus.mock.calls).toEqual([[{preventScroll: true}]]);
+  });
+
+  it('clears a ring the browser already drew before refocusing after pointer input', () => {
+    const element = button();
+    element.focus();
+    document.dispatchEvent(new Event('pointerdown'));
+    const matches = HTMLElement.prototype.matches;
+    vi.spyOn(HTMLElement.prototype, 'matches').mockImplementation(function (
+      this: HTMLElement,
+      selector: string,
+    ) {
+      return selector === ':focus-visible'
+        ? this === element
+        : matches.call(this, selector);
+    });
+    const blur = vi.spyOn(element, 'blur');
+    const focus = vi.spyOn(element, 'focus');
+    focusForLastInput(element, {preventScroll: true});
+    expect(blur).toHaveBeenCalledTimes(1);
+    expect(focus.mock.calls).toEqual([
+      [{preventScroll: true, focusVisible: false}],
+    ]);
+    expect(blur.mock.invocationCallOrder[0]).toBeLessThan(
+      focus.mock.invocationCallOrder[0] ?? 0,
+    );
+    expect(document.activeElement).toBe(element);
+  });
+});

package/src/utils/focusReturn.ts

@@ -2,13 +2,18 @@
 
 /**
  * @file focusReturn.ts
- * @input The document's current active element.
- * @output Whether focus is currently "detached" — on nothing in particular.
+ * @input The document's current active element and the shared interaction
+ *   modality.
+ * @output Whether focus is currently "detached" — on nothing in particular —
+ *   and a focus move whose ring follows the last input.
  * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
  *   that return focus to their control when the overlay closes, but only when
- *   the dismiss did not already move focus somewhere the user chose.
+ *   the dismiss did not already move focus somewhere the user chose, and by
+ *   overlays (Dialog, DropdownMenu) that move focus programmatically.
  */
 
+import {getInteractionModality} from './interactionModality';
+
 /**
  * True when focus rests on nothing in particular — no active element, or the
  * document body / root element.
@@ -29,3 +34,43 @@ export function isFocusDetached(doc: Document = document): boolean {
     active == null || active === doc.body || active === doc.documentElement
   );
 }
+
+/**
+ * Move focus programmatically so its ring follows the last input
+ * (`architecture:interaction-modality` INV1). After pointer input the browser's
+ * focus option keeps the element from matching `:focus-visible`, which is the
+ * one way to reach an element the overlay does not render: the consumer's
+ * autofocus target, the control that opened a Dialog, or a menu trigger the
+ * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
+ *
+ * Make sure modality tracking is active (`useInteractionModalityTracking()`)
+ * in the component that calls this.
+ */
+export function focusForLastInput(
+  element: HTMLElement,
+  options?: FocusOptions,
+): void {
+  // A text-entry field paints its own focus treatment to show where typing
+  // goes, and an extra blur there can run validation or mark it touched.
+  const isTextEntry =
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement ||
+    element.isContentEditable;
+  if (isTextEntry || getInteractionModality() !== 'pointer') {
+    if (options === undefined) {
+      element.focus();
+    } else {
+      element.focus(options);
+    }
+    return;
+  }
+  // Focusing the element that already has focus does nothing, so a ring the
+  // browser already drew would stay. WebKit draws one when its own focus
+  // restoration (a dialog's close, a popover's hide) moves focus itself, so
+  // clear that focus first.
+  if (element.matches(':focus-visible')) {
+    element.blur();
+  }
+  element.focus({...options, focusVisible: false});
+}