@baukit/ui-tokens 0.7.2 → 0.7.3

package/src/layout.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  getLayoutMode,
+  getScreenMaxWidth,
+  getTabContentInset,
+  getUsableContentHeight,
+  isShortViewport,
+  type LayoutBreakpoints,
+} from './layout.js';
+
+const BREAKPOINTS: LayoutBreakpoints = { medium: 768, expanded: 1024 };
+
+const MAX_WIDTHS = { form: 720, reading: 720, dashboard: 1200 } as const;
+
+const WIDTH_OPTIONS = {
+  maxWidths: MAX_WIDTHS,
+  narrowFallback: 'reading',
+  expandedOnly: ['dashboard'],
+} as const;
+
+describe('getLayoutMode', () => {
+  it.each([
+    [0, 'compact'],
+    [767, 'compact'],
+    [768, 'medium'],
+    [1023, 'medium'],
+    [1024, 'expanded'],
+    [1920, 'expanded'],
+  ])('classifies width %i as %s', (width, expected) => {
+    expect(getLayoutMode(width, BREAKPOINTS)).toBe(expected);
+  });
+
+  it('follows the breakpoints it is given, not a built-in set', () => {
+    const wide: LayoutBreakpoints = { medium: 1000, expanded: 1600 };
+
+    expect(getLayoutMode(900, wide)).toBe('compact');
+    expect(getLayoutMode(900, BREAKPOINTS)).toBe('medium');
+  });
+});
+
+describe('getScreenMaxWidth', () => {
+  it('returns the named width when the mode allows it', () => {
+    expect(getScreenMaxWidth('dashboard', 'expanded', WIDTH_OPTIONS)).toBe(1200);
+    expect(getScreenMaxWidth('form', 'compact', WIDTH_OPTIONS)).toBe(720);
+  });
+
+  it.each(['compact', 'medium'] as const)('narrows an expanded-only screen in %s', (mode) => {
+    expect(getScreenMaxWidth('dashboard', mode, WIDTH_OPTIONS)).toBe(MAX_WIDTHS.reading);
+  });
+
+  it('leaves screens outside the expanded-only list alone', () => {
+    expect(getScreenMaxWidth('form', 'medium', WIDTH_OPTIONS)).toBe(720);
+  });
+
+  it('rejects a screen name the product did not define', () => {
+    // Products that build the option set at runtime lose the compile-time check.
+    const unknown = 'missing' as keyof typeof MAX_WIDTHS;
+
+    expect(() => getScreenMaxWidth(unknown, 'expanded', WIDTH_OPTIONS)).toThrow(
+      'unknown screen max width: missing',
+    );
+  });
+});
+
+describe('getTabContentInset', () => {
+  it('adds the tab bar and safe area below the expanded mode', () => {
+    expect(getTabContentInset('compact', 34, 56)).toBe(90);
+    expect(getTabContentInset('medium', 0, 56)).toBe(56);
+  });
+
+  it('needs no inset once the tab bar becomes a rail', () => {
+    expect(getTabContentInset('expanded', 34, 56)).toBe(0);
+  });
+
+  it('ignores a negative safe area', () => {
+    expect(getTabContentInset('compact', -10, 56)).toBe(56);
+  });
+});
+
+describe('getUsableContentHeight', () => {
+  it('subtracts footer and inset and clamps the result at zero', () => {
+    expect(getUsableContentHeight(720, 112, 128)).toBe(480);
+    expect(getUsableContentHeight(100, 112, 56)).toBe(0);
+    expect(getUsableContentHeight(0, 0, 0)).toBe(0);
+  });
+
+  it.each([
+    ['viewportHeight', Number.NaN, 0, 0],
+    ['viewportHeight', Number.POSITIVE_INFINITY, 0, 0],
+    ['viewportHeight', -1, 0, 0],
+    ['fixedFooterHeight', 100, Number.NaN, 0],
+    ['fixedFooterHeight', 100, Number.POSITIVE_INFINITY, 0],
+    ['fixedFooterHeight', 100, -1, 0],
+    ['bottomInset', 100, 0, Number.NaN],
+    ['bottomInset', 100, 0, Number.POSITIVE_INFINITY],
+    ['bottomInset', 100, 0, -1],
+  ] as const)('rejects an invalid %s', (name, viewportHeight, footerHeight, bottomInset) => {
+    expect(() => getUsableContentHeight(viewportHeight, footerHeight, bottomInset)).toThrow(
+      `${name} must be a finite non-negative number`,
+    );
+  });
+});
+
+describe('isShortViewport', () => {
+  it('includes the caller-supplied threshold boundary', () => {
+    expect(isShortViewport(599, 600)).toBe(true);
+    expect(isShortViewport(600, 600)).toBe(true);
+    expect(isShortViewport(601, 600)).toBe(false);
+  });
+
+  it.each([
+    [Number.NaN, 600, 'viewportHeight'],
+    [Number.POSITIVE_INFINITY, 600, 'viewportHeight'],
+    [-1, 600, 'viewportHeight'],
+    [600, Number.NaN, 'threshold'],
+    [600, Number.POSITIVE_INFINITY, 'threshold'],
+    [600, -1, 'threshold'],
+  ] as const)('rejects invalid dimensions', (viewportHeight, threshold, name) => {
+    expect(() => isShortViewport(viewportHeight, threshold)).toThrow(
+      `${name} must be a finite non-negative number`,
+    );
+  });
+});

package/src/layout.ts

@@ -0,0 +1,81 @@
+/**
+ * Layout mode arithmetic over a product's own breakpoint numbers. The rules are
+ * shared; the numbers are not, so every function takes them as an argument.
+ */
+
+export type LayoutMode = 'compact' | 'medium' | 'expanded';
+
+export interface LayoutBreakpoints {
+  /** Width at or above which the layout is `medium`. */
+  readonly medium: number;
+  /** Width at or above which the layout is `expanded`. */
+  readonly expanded: number;
+}
+
+export type ScreenMaxWidths = Readonly<Record<string, number>>;
+
+export interface ScreenMaxWidthOptions<Widths extends ScreenMaxWidths> {
+  readonly maxWidths: Widths;
+  /** Key used when a wide screen is requested below the `expanded` mode. */
+  readonly narrowFallback: keyof Widths;
+  /** Keys that only reach their full width in the `expanded` mode. */
+  readonly expandedOnly: readonly (keyof Widths)[];
+}
+
+/** Classifies a viewport width. Ties go to the wider mode. */
+export function getLayoutMode(width: number, breakpoints: LayoutBreakpoints): LayoutMode {
+  if (width >= breakpoints.expanded) return 'expanded';
+  if (width >= breakpoints.medium) return 'medium';
+  return 'compact';
+}
+
+/** Resolves a named content width, narrowing expanded-only keys below that mode. */
+export function getScreenMaxWidth<Widths extends ScreenMaxWidths>(
+  screen: keyof Widths,
+  layoutMode: LayoutMode,
+  { maxWidths, narrowFallback, expandedOnly }: ScreenMaxWidthOptions<Widths>,
+): number {
+  const key = layoutMode !== 'expanded' && expandedOnly.includes(screen) ? narrowFallback : screen;
+  const width = maxWidths[key];
+  if (width === undefined) {
+    throw new Error(`unknown screen max width: ${String(key)}`);
+  }
+  return width;
+}
+
+/** Bottom padding that keeps content clear of a mobile tab bar and the safe area. */
+export function getTabContentInset(
+  layoutMode: LayoutMode,
+  safeAreaBottom: number,
+  tabBarHeight: number,
+): number {
+  if (layoutMode === 'expanded') return 0;
+  return tabBarHeight + Math.max(0, safeAreaBottom);
+}
+
+function validateNonNegativeDimension(name: string, value: number): void {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `${name} must be a finite non-negative number; received ${String(value)}.`,
+    );
+  }
+}
+
+/** Returns the viewport height left after fixed footer and bottom inset. */
+export function getUsableContentHeight(
+  viewportHeight: number,
+  fixedFooterHeight: number,
+  bottomInset: number,
+): number {
+  validateNonNegativeDimension('viewportHeight', viewportHeight);
+  validateNonNegativeDimension('fixedFooterHeight', fixedFooterHeight);
+  validateNonNegativeDimension('bottomInset', bottomInset);
+  return Math.max(0, viewportHeight - fixedFooterHeight - bottomInset);
+}
+
+/** True when the viewport height is at or below the caller's threshold. */
+export function isShortViewport(viewportHeight: number, threshold: number): boolean {
+  validateNonNegativeDimension('viewportHeight', viewportHeight);
+  validateNonNegativeDimension('threshold', threshold);
+  return viewportHeight <= threshold;
+}

package/src/schema.ts

@@ -0,0 +1,46 @@
+export interface ThemeColor {
+  /** A three- or six-digit hexadecimal sRGB color. */
+  readonly light: string;
+  /** A three- or six-digit hexadecimal sRGB color. */
+  readonly dark: string;
+}
+
+export interface ColorTokenGroup {
+  readonly [name: string]: ColorTokenGroup | ThemeColor;
+}
+
+export type TokenScale<T> = Readonly<Record<string, T>>;
+
+export type DimensionValue = number | string;
+
+export interface TypographyTokens {
+  readonly family: TokenScale<string>;
+  readonly size: TokenScale<DimensionValue>;
+  readonly weight: TokenScale<number>;
+  readonly lineHeight: TokenScale<DimensionValue>;
+}
+
+export interface MotionTokens {
+  readonly duration: TokenScale<DimensionValue>;
+  readonly easing: TokenScale<string>;
+}
+
+export interface ContrastPair {
+  /** A complete semantic path such as `color.text.primary`. */
+  readonly foreground: string;
+  /** A complete semantic path such as `color.background.primary`. */
+  readonly background: string;
+  /** Large text uses WCAG's 3:1 threshold instead of 4.5:1. */
+  readonly largeText?: boolean;
+}
+
+/** Cross-platform token source. It intentionally contains no component definitions. */
+export interface DesignTokens {
+  readonly color: ColorTokenGroup;
+  readonly typography: TypographyTokens;
+  readonly space: TokenScale<DimensionValue>;
+  readonly radius: TokenScale<DimensionValue>;
+  readonly motion: MotionTokens;
+  readonly elevation: TokenScale<DimensionValue>;
+  readonly contrastPairs: readonly ContrastPair[];
+}

package/src/validation.ts

@@ -0,0 +1,237 @@
+import type { DesignTokens, ThemeColor } from './schema.js';
+
+export interface ValidationIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+const TOKEN_NAME = /^[a-z][A-Za-z0-9]*$/u;
+const HEX_COLOR = /^#[\dA-Fa-f]{3}(?:[\dA-Fa-f]{3})?$/u;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(issues: ValidationIssue[], path: string, message: string): void {
+  issues.push({ path, message });
+}
+
+function validateKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  issues: ValidationIssue[],
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      issue(issues, `${path}.${key}`, 'is not a recognized field');
+    }
+  }
+  for (const key of allowed) {
+    if (!(key in value)) {
+      issue(issues, `${path}.${key}`, 'is required');
+    }
+  }
+}
+
+function validateTokenName(name: string, path: string, issues: ValidationIssue[]): void {
+  if (!TOKEN_NAME.test(name)) {
+    issue(issues, path, 'must start with a lowercase letter and contain only letters or digits');
+  }
+}
+
+function validateColorGroup(
+  value: unknown,
+  path: string,
+  depth: number,
+  issues: ValidationIssue[],
+): void {
+  if (!isRecord(value)) {
+    issue(issues, path, 'must be a color token group');
+    return;
+  }
+
+  const isLeaf = 'light' in value || 'dark' in value;
+  if (isLeaf) {
+    validateKeys(value, ['light', 'dark'], path, issues);
+    if (depth < 2) {
+      issue(
+        issues,
+        path,
+        'must use a semantic group and token name (for example background.primary)',
+      );
+    }
+    for (const theme of ['light', 'dark'] as const) {
+      const color = value[theme];
+      if (typeof color !== 'string' || !HEX_COLOR.test(color)) {
+        issue(issues, `${path}.${theme}`, 'must be a #RGB or #RRGGBB hexadecimal color');
+      }
+    }
+    return;
+  }
+
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    issue(issues, path, 'must contain at least one token');
+  }
+  for (const [name, child] of entries) {
+    validateTokenName(name, `${path}.${name}`, issues);
+    validateColorGroup(child, `${path}.${name}`, depth + 1, issues);
+  }
+}
+
+type ScalarKind = 'dimension' | 'positive-dimension' | 'string' | 'weight';
+
+function validScalar(value: unknown, kind: ScalarKind): boolean {
+  if (kind === 'string') {
+    return typeof value === 'string' && value.length > 0;
+  }
+  if (kind === 'weight') {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 1000;
+  }
+  if (typeof value === 'string') {
+    return value.length > 0;
+  }
+  return (
+    typeof value === 'number' &&
+    Number.isFinite(value) &&
+    (kind === 'positive-dimension' ? value > 0 : value >= 0)
+  );
+}
+
+function validateScale(
+  value: unknown,
+  path: string,
+  kind: ScalarKind,
+  issues: ValidationIssue[],
+): void {
+  if (!isRecord(value)) {
+    issue(issues, path, 'must be a token scale');
+    return;
+  }
+  const entries = Object.entries(value);
+  if (entries.length === 0) {
+    issue(issues, path, 'must contain at least one token');
+  }
+  for (const [name, token] of entries) {
+    const tokenPath = `${path}.${name}`;
+    validateTokenName(name, tokenPath, issues);
+    if (!validScalar(token, kind)) {
+      issue(issues, tokenPath, `must be a valid ${kind.replace('-', ' ')}`);
+    }
+  }
+}
+
+function validateTypography(value: unknown, issues: ValidationIssue[]): void {
+  if (!isRecord(value)) {
+    issue(issues, '$.typography', 'must be an object');
+    return;
+  }
+  validateKeys(value, ['family', 'size', 'weight', 'lineHeight'], '$.typography', issues);
+  validateScale(value['family'], '$.typography.family', 'string', issues);
+  validateScale(value['size'], '$.typography.size', 'positive-dimension', issues);
+  validateScale(value['weight'], '$.typography.weight', 'weight', issues);
+  validateScale(value['lineHeight'], '$.typography.lineHeight', 'positive-dimension', issues);
+}
+
+function validateMotion(value: unknown, issues: ValidationIssue[]): void {
+  if (!isRecord(value)) {
+    issue(issues, '$.motion', 'must be an object');
+    return;
+  }
+  validateKeys(value, ['duration', 'easing'], '$.motion', issues);
+  validateScale(value['duration'], '$.motion.duration', 'dimension', issues);
+  validateScale(value['easing'], '$.motion.easing', 'string', issues);
+}
+
+function findColor(value: unknown, path: string): ThemeColor | undefined {
+  const segments = path.split('.');
+  if (segments.shift() !== 'color') {
+    return undefined;
+  }
+  let current: unknown = value;
+  for (const segment of segments) {
+    if (!isRecord(current)) {
+      return undefined;
+    }
+    current = current[segment];
+  }
+  if (
+    isRecord(current) &&
+    typeof current['light'] === 'string' &&
+    typeof current['dark'] === 'string'
+  ) {
+    return current as unknown as ThemeColor;
+  }
+  return undefined;
+}
+
+function validateContrastPairs(value: unknown, colors: unknown, issues: ValidationIssue[]): void {
+  if (!Array.isArray(value)) {
+    issue(issues, '$.contrastPairs', 'must be an array');
+    return;
+  }
+  value.forEach((pair: unknown, index: number) => {
+    const path = `$.contrastPairs[${String(index)}]`;
+    if (!isRecord(pair)) {
+      issue(issues, path, 'must be an object');
+      return;
+    }
+    for (const key of Object.keys(pair)) {
+      if (!['foreground', 'background', 'largeText'].includes(key)) {
+        issue(issues, `${path}.${key}`, 'is not a recognized field');
+      }
+    }
+    for (const role of ['foreground', 'background'] as const) {
+      const colorPath = pair[role];
+      if (typeof colorPath !== 'string' || findColor(colors, colorPath) === undefined) {
+        issue(issues, `${path}.${role}`, 'must reference an existing color token path');
+      }
+    }
+    if ('largeText' in pair && typeof pair['largeText'] !== 'boolean') {
+      issue(issues, `${path}.largeText`, 'must be a boolean');
+    }
+  });
+}
+
+/** Returns every structural problem with a path rooted at `$`. */
+export function validateTokens(input: unknown): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+  if (!isRecord(input)) {
+    return [{ path: '$', message: 'must be an object' }];
+  }
+
+  validateKeys(
+    input,
+    ['color', 'typography', 'space', 'radius', 'motion', 'elevation', 'contrastPairs'],
+    '$',
+    issues,
+  );
+  validateColorGroup(input['color'], '$.color', 0, issues);
+  validateTypography(input['typography'], issues);
+  validateScale(input['space'], '$.space', 'dimension', issues);
+  validateScale(input['radius'], '$.radius', 'dimension', issues);
+  validateMotion(input['motion'], issues);
+  validateScale(input['elevation'], '$.elevation', 'dimension', issues);
+  validateContrastPairs(input['contrastPairs'], input['color'], issues);
+  return issues;
+}
+
+export class TokenValidationError extends Error {
+  public readonly issues: readonly ValidationIssue[];
+
+  public constructor(issues: readonly ValidationIssue[]) {
+    super(issues.map(({ path, message }) => `${path}: ${message}`).join('\n'));
+    this.name = 'TokenValidationError';
+    this.issues = issues;
+  }
+}
+
+/** Validates unknown input and returns it with the design-token type. */
+export function parseTokens(input: unknown): DesignTokens {
+  const issues = validateTokens(input);
+  if (issues.length > 0) {
+    throw new TokenValidationError(issues);
+  }
+  return input as DesignTokens;
+}