@ccslabs/xtend 0.1.0-rc.1

package/a11y/screenreader-signals.d.ts

@@ -0,0 +1,32 @@
+export * from '../fabric/xtend-policy-public-types';
+import type {
+  XtendA11ySignal,
+  XtendPolicyConstant,
+  XtendPolicyFunction,
+  XtendPolicyOptions,
+  XtendPolicyReport
+} from '../fabric/xtend-policy-public-types';
+
+export interface XtendScreenreaderSignalContract {
+  schema: string;
+  componentRef: string;
+  liveRegion: string;
+  signals: XtendA11ySignal[];
+  statusRegions: unknown[];
+  errorRegions: unknown[];
+  announcementPolicy: Record<string, unknown>;
+  fabric: Record<string, unknown>;
+  requiredAssertions: string[];
+  [key: string]: unknown;
+}
+
+export declare const CONTRACTS: XtendPolicyConstant<Record<string, string>>;
+export declare const FABRIC_A11Y_ANNOUNCEMENT: XtendPolicyConstant<Record<string, unknown>>;
+export declare const LIVE_REGION_POLICIES: XtendPolicyConstant<Record<string, unknown>>;
+export declare const SCREENREADER_SIGNALS_SCHEMA: XtendPolicyConstant<string>;
+export declare const SCREENREADER_SIGNAL_DEFINITIONS: XtendPolicyConstant<Record<string, unknown>>;
+export declare const SCREENREADER_SIGNAL_RECORD_SCHEMA: XtendPolicyConstant<string>;
+export declare function createScreenreaderSignal(signal: string, options?: XtendPolicyOptions): XtendA11ySignal;
+export declare function createScreenreaderSignalContract(componentRef?: string, options?: XtendPolicyOptions): XtendScreenreaderSignalContract;
+export declare const normalizeLiveRegion: XtendPolicyFunction<string>;
+export declare function validateScreenreaderSignalContract(contract: unknown): XtendPolicyReport;

package/a11y/screenreader-signals.js

@@ -0,0 +1,372 @@
+(function attachXtendA11yScreenreaderSignals(globalTarget, factory) {
+  const api = factory();
+
+  if (typeof module === 'object' && module.exports) {
+    module.exports = api;
+  }
+
+  if (globalTarget && typeof globalTarget === 'object') {
+    globalTarget.XTendA11yScreenreaderSignals = Object.freeze({
+      schema: api.SCREENREADER_SIGNALS_SCHEMA,
+      contracts: api.CONTRACTS,
+      definitions: api.SCREENREADER_SIGNAL_DEFINITIONS,
+      liveRegionPolicies: api.LIVE_REGION_POLICIES,
+      createScreenreaderSignal: api.createScreenreaderSignal,
+      createScreenreaderSignalContract: api.createScreenreaderSignalContract,
+      normalizeLiveRegion: api.normalizeLiveRegion,
+      validateScreenreaderSignalContract: api.validateScreenreaderSignalContract
+    });
+  }
+})(typeof globalThis !== 'undefined' ? globalThis : this, function createXtendA11yScreenreaderSignalsModule() {
+  const CONTRACTS = Object.freeze({
+    screenreaderSignals: 'xtend.a11y.screenreader-signals.v1',
+    signal: 'xtend.a11y.screenreader-signal.v1',
+    profile: 'xtend.a11y.profile.v1',
+    test: 'xtend.a11y.test-contract.v1',
+    fabricLaneMapping: 'xtend.fabric.rmt-lane-mapping.v1'
+  });
+
+  const SCREENREADER_SIGNALS_SCHEMA = CONTRACTS.screenreaderSignals;
+  const SCREENREADER_SIGNAL_RECORD_SCHEMA = CONTRACTS.signal;
+
+  const LIVE_REGION_POLICIES = Object.freeze({
+    none: Object.freeze({
+      politeness: 'off',
+      requiresRegion: false,
+      roles: []
+    }),
+    polite: Object.freeze({
+      politeness: 'polite',
+      requiresRegion: true,
+      roles: ['status', 'log']
+    }),
+    assertive: Object.freeze({
+      politeness: 'assertive',
+      requiresRegion: true,
+      roles: ['alert']
+    })
+  });
+
+  const SCREENREADER_SIGNAL_DEFINITIONS = Object.freeze({
+    'semantic-region': Object.freeze({
+      kind: 'semantic',
+      liveRegion: 'none',
+      region: 'semantic',
+      role: 'region',
+      assertions: ['role-or-native-semantics', 'accessible-name']
+    }),
+    'state-change-announcement': Object.freeze({
+      kind: 'state',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['state-change-announcement', 'duplicate-announcement-guard']
+    }),
+    'state-change-summary': Object.freeze({
+      kind: 'state',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['state-change-summary', 'aria-busy-consistency']
+    }),
+    'status-announcement': Object.freeze({
+      kind: 'status',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['status-region', 'aria-live-polite', 'non-empty-announcement']
+    }),
+    'dismissal-announcement': Object.freeze({
+      kind: 'status',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['dismissal-announcement', 'duplicate-announcement-guard']
+    }),
+    'dialog-context': Object.freeze({
+      kind: 'context',
+      liveRegion: 'none',
+      region: 'dialog',
+      role: 'dialog',
+      assertions: ['aria-modal', 'aria-labelledby-or-label']
+    }),
+    'focus-return': Object.freeze({
+      kind: 'focus',
+      liveRegion: 'none',
+      region: 'focus',
+      role: null,
+      assertions: ['focus-return', 'escape-close']
+    }),
+    'route-change-announcement': Object.freeze({
+      kind: 'navigation',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['route-change-announcement', 'active-route-focus']
+    }),
+    'contrast-preservation': Object.freeze({
+      kind: 'theme',
+      liveRegion: 'none',
+      region: 'semantic',
+      role: 'region',
+      assertions: ['no-color-only-state', 'focus-visible-token']
+    }),
+    'validation-error-summary': Object.freeze({
+      kind: 'error',
+      liveRegion: 'assertive',
+      region: 'error',
+      role: 'alert',
+      assertions: ['error-region', 'aria-live-assertive', 'validation-error-summary']
+    }),
+    'submit-status': Object.freeze({
+      kind: 'status',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['submit-status', 'non-empty-announcement']
+    }),
+    'loading-state': Object.freeze({
+      kind: 'status',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['loading-announcement', 'aria-busy-consistency']
+    }),
+    'control-state': Object.freeze({
+      kind: 'state',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['control-state-announcement', 'keyboard-state-sync']
+    })
+  });
+
+  const FABRIC_A11Y_ANNOUNCEMENT = Object.freeze({
+    lane: 'a11y',
+    fiberKind: 'a11y.announce',
+    scheduleRef: 'a11y.user-blocking.announce',
+    scheduleContract: CONTRACTS.fabricLaneMapping,
+    boundary: 'fabric-adapter-schedules-announcement-rmt-kernel-remains-framework-agnostic'
+  });
+
+  function unique(values) {
+    return Array.from(new Set((values || []).filter(Boolean)));
+  }
+
+  function normalizeLiveRegion(value, fallback = 'none') {
+    const normalized = String(value || fallback || 'none').trim().toLowerCase();
+    return Object.prototype.hasOwnProperty.call(LIVE_REGION_POLICIES, normalized)
+      ? normalized
+      : normalizeLiveRegion(fallback, 'none');
+  }
+
+  function getSignalDefinition(signal) {
+    return SCREENREADER_SIGNAL_DEFINITIONS[signal] || Object.freeze({
+      kind: 'custom',
+      liveRegion: 'polite',
+      region: 'status',
+      role: 'status',
+      assertions: ['custom-screenreader-signal']
+    });
+  }
+
+  function normalizeSignalNames(input = {}) {
+    const profileSignals = input.profile
+      && input.profile.screenreader
+      && Array.isArray(input.profile.screenreader.signals)
+      ? input.profile.screenreader.signals
+      : [];
+    const directSignals = Array.isArray(input.signals) ? input.signals : [];
+    const screenreaderSignals = input.screenreader
+      && Array.isArray(input.screenreader.signals)
+      ? input.screenreader.signals
+      : [];
+
+    return unique(profileSignals.concat(directSignals, screenreaderSignals).map((signal) => {
+      if (typeof signal === 'string') return signal;
+      return signal && signal.signal ? String(signal.signal) : null;
+    }));
+  }
+
+  function resolveComponentRef(input = {}) {
+    return input.componentRef || input.tag || (input.profile && input.profile.componentRef) || 'x-component';
+  }
+
+  function createRegionRecord(signalRecord, kind) {
+    const livePolicy = LIVE_REGION_POLICIES[signalRecord.liveRegion] || LIVE_REGION_POLICIES.none;
+    return {
+      id: `${signalRecord.componentRef}.${signalRecord.signal}.${kind}-region`,
+      sourceSignal: signalRecord.signal,
+      kind,
+      role: signalRecord.role || (kind === 'error' ? 'alert' : 'status'),
+      ariaLive: signalRecord.liveRegion,
+      ariaAtomic: true,
+      required: signalRecord.required === true && livePolicy.requiresRegion === true
+    };
+  }
+
+  function createScreenreaderSignal(signal, defaults = {}) {
+    const input = typeof signal === 'string' ? { signal } : (signal || {});
+    const signalName = String(input.signal || 'custom-announcement');
+    const definition = getSignalDefinition(signalName);
+    const liveRegion = normalizeLiveRegion(input.liveRegion || definition.liveRegion || defaults.liveRegion);
+    const livePolicy = LIVE_REGION_POLICIES[liveRegion] || LIVE_REGION_POLICIES.none;
+    const kind = input.kind || definition.kind || 'custom';
+    const region = input.region || definition.region || (kind === 'error' ? 'error' : 'status');
+    const role = input.role === undefined ? definition.role : input.role;
+
+    return {
+      schema: SCREENREADER_SIGNAL_RECORD_SCHEMA,
+      contract: SCREENREADER_SIGNALS_SCHEMA,
+      componentRef: defaults.componentRef || resolveComponentRef(defaults),
+      signal: signalName,
+      kind,
+      region,
+      role: role || null,
+      liveRegion,
+      politeness: livePolicy.politeness,
+      required: input.required !== false,
+      announcement: {
+        mode: input.mode || (liveRegion === 'none' ? 'focus-or-semantic-context' : 'live-region-text'),
+        source: input.source || 'component-state',
+        textRequired: liveRegion !== 'none',
+        emptyStringAllowed: false,
+        duplicateSuppression: 'same-signal-and-text'
+      },
+      aria: {
+        live: liveRegion === 'none' ? null : liveRegion,
+        atomic: liveRegion === 'none' ? null : true,
+        role: role || null
+      },
+      fabric: FABRIC_A11Y_ANNOUNCEMENT,
+      assertions: unique(definition.assertions || [])
+    };
+  }
+
+  function createScreenreaderSignalContract(input = {}) {
+    const componentRef = resolveComponentRef(input);
+    const signalNames = normalizeSignalNames(input);
+    const profileLiveRegion = input.profile
+      && input.profile.screenreader
+      ? input.profile.screenreader.liveRegion
+      : null;
+    const defaultLiveRegion = normalizeLiveRegion(input.liveRegion || profileLiveRegion);
+    const signals = signalNames.map((signal) => createScreenreaderSignal(signal, {
+      componentRef,
+      liveRegion: defaultLiveRegion
+    }));
+    const statusRegions = signals
+      .filter((record) => record.region === 'status' && record.liveRegion !== 'none')
+      .map((record) => createRegionRecord(record, 'status'));
+    const errorRegions = signals
+      .filter((record) => record.region === 'error' && record.liveRegion !== 'none')
+      .map((record) => createRegionRecord(record, 'error'));
+    const requiredAssertions = unique([
+      'screenreader-signal-contract',
+      signals.some((record) => record.liveRegion !== 'none') ? 'aria-live-policy' : null,
+      statusRegions.length > 0 ? 'status-region-policy' : null,
+      errorRegions.length > 0 ? 'error-region-policy' : null,
+      'announcement-policy',
+      'fabric-a11y-lane'
+    ]);
+
+    return {
+      schema: SCREENREADER_SIGNALS_SCHEMA,
+      status: 'accepted-contract',
+      componentRef,
+      profileRef: input.primaryProfile || (input.profile && input.profile.primaryProfile) || null,
+      liveRegion: defaultLiveRegion,
+      signals,
+      statusRegions,
+      errorRegions,
+      announcementPolicy: {
+        required: signals.some((record) => record.required),
+        noSilentStateChanges: true,
+        emptyAnnouncementsRefused: true,
+        duplicateSuppression: 'same-signal-and-text',
+        defaultLiveRegion
+      },
+      fabric: FABRIC_A11Y_ANNOUNCEMENT,
+      testRefs: ['a11y-hydration', 'screenreader-signals', 'references'],
+      requiredAssertions
+    };
+  }
+
+  function validateScreenreaderSignalContract(contract) {
+    const errors = [];
+    const warnings = [];
+
+    if (!contract || typeof contract !== 'object') {
+      return { ok: false, errors: ['contract must be an object'], warnings };
+    }
+
+    if (contract.schema !== SCREENREADER_SIGNALS_SCHEMA) {
+      errors.push(`schema must be ${SCREENREADER_SIGNALS_SCHEMA}`);
+    }
+
+    if (typeof contract.componentRef !== 'string' || contract.componentRef.length === 0) {
+      errors.push('componentRef must be a non-empty string');
+    }
+
+    if (!Array.isArray(contract.signals) || contract.signals.length === 0) {
+      errors.push('signals must contain at least one screenreader signal record');
+    } else {
+      contract.signals.forEach((record, index) => {
+        if (!record || typeof record !== 'object') {
+          errors.push(`signals[${index}] must be an object`);
+          return;
+        }
+        if (record.schema !== SCREENREADER_SIGNAL_RECORD_SCHEMA) {
+          errors.push(`signals[${index}].schema must be ${SCREENREADER_SIGNAL_RECORD_SCHEMA}`);
+        }
+        if (typeof record.signal !== 'string' || record.signal.length === 0) {
+          errors.push(`signals[${index}].signal must be a non-empty string`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(LIVE_REGION_POLICIES, record.liveRegion)) {
+          errors.push(`signals[${index}].liveRegion must be none, polite or assertive`);
+        }
+        if (record.liveRegion !== 'none' && (!record.aria || record.aria.live !== record.liveRegion)) {
+          errors.push(`signals[${index}] must mirror liveRegion into aria.live`);
+        }
+        if (record.required === true && record.region === 'status') {
+          const statusRegion = Array.isArray(contract.statusRegions)
+            && contract.statusRegions.some((region) => region.sourceSignal === record.signal);
+          if (!statusRegion) errors.push(`status signal ${record.signal} requires a status region`);
+        }
+        if (record.required === true && record.region === 'error') {
+          const errorRegion = Array.isArray(contract.errorRegions)
+            && contract.errorRegions.some((region) => region.sourceSignal === record.signal);
+          if (!errorRegion) errors.push(`error signal ${record.signal} requires an error region`);
+        }
+      });
+    }
+
+    if (!contract.fabric || contract.fabric.lane !== 'a11y' || contract.fabric.fiberKind !== 'a11y.announce') {
+      errors.push('fabric mapping must use lane a11y and fiber kind a11y.announce');
+    }
+
+    if (Array.isArray(contract.signals) && contract.signals.length > 0 && contract.statusRegions && contract.statusRegions.length === 0) {
+      const hasLiveStatusSignal = contract.signals.some((record) => record.region === 'status' && record.liveRegion !== 'none');
+      if (hasLiveStatusSignal) warnings.push('live status signals exist without status regions');
+    }
+
+    return {
+      ok: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+
+  return {
+    CONTRACTS,
+    FABRIC_A11Y_ANNOUNCEMENT,
+    LIVE_REGION_POLICIES,
+    SCREENREADER_SIGNALS_SCHEMA,
+    SCREENREADER_SIGNAL_DEFINITIONS,
+    SCREENREADER_SIGNAL_RECORD_SCHEMA,
+    createScreenreaderSignal,
+    createScreenreaderSignalContract,
+    normalizeLiveRegion,
+    validateScreenreaderSignalContract
+  };
+});

package/api.d.ts

@@ -0,0 +1,168 @@
+export type XTendFeedbackType = 'info' | 'success' | 'warning' | 'error';
+export type XTendManifest = Record<string, string>;
+export type XTendThemeTokenMap = Record<string, string>;
+export type XTendThemeRegistry = Record<string, Record<string, unknown>>;
+export type XTendUnsubscribe = () => void;
+
+export interface XTendApiReadyDetail {
+  schema: 'xtend.api.ready.v1';
+  toast: boolean;
+  alert: boolean;
+  dialog: boolean;
+  modal: boolean;
+  theme: boolean;
+}
+
+export interface XTendComplianceApi {
+  version: string;
+  getChecklist(): string[];
+  getCoreContracts(): Record<string, string[]>;
+  getThemeTokens(themeName?: string): XTendThemeTokenMap | Record<string, unknown>;
+}
+
+export interface XTendThemeChangePayload {
+  theme?: string;
+  currentTheme?: string;
+  availableThemes?: string[];
+  [key: string]: unknown;
+}
+
+export interface XTendThemeApi {
+  getCurrentTheme(): string | null;
+  getAvailableThemes(): string[];
+  setTheme(themeName: string): boolean;
+  set(name: string, value?: string): boolean;
+  get(name?: string): string | null;
+  subscribe(subscriber: (payload: XTendThemeChangePayload) => void): XTendUnsubscribe;
+  toggleDarkMode(): boolean;
+  loadExternalTheme(themeName: string, cssUrl: string): Promise<unknown>;
+  registerTheme(name: string, properties?: XTendThemeTokenMap | Record<string, unknown>): boolean;
+  removeTheme(themeName: string): boolean;
+  getThemeInfo(themeName: string): Record<string, unknown> | null;
+  getAllThemeInfo(): XTendThemeRegistry;
+  hasTheme(themeName: string): boolean;
+  getThemeRegistry(): XTendThemeRegistry;
+  listenToSystemTheme(enabled?: boolean): void;
+  [key: string]: unknown;
+}
+
+export interface XTendToastState {
+  id: string;
+  message: string;
+  type: XTendFeedbackType;
+  duration: number;
+  timestamp: number;
+}
+
+export interface XTendToastApi {
+  show(message: string, type?: XTendFeedbackType | string, duration?: number): HTMLElement;
+  success(message: string, duration?: number): HTMLElement;
+  error(message: string, duration?: number): HTMLElement;
+  warning(message: string, duration?: number): HTMLElement;
+  info(message: string, duration?: number): HTMLElement;
+  clearAll(): void;
+}
+
+export interface XTendAlertOptions {
+  closable?: boolean;
+  duration?: number;
+  overlay?: boolean;
+  ariaLabel?: string;
+}
+
+export interface XTendAlertState extends XTendAlertOptions {
+  id: string;
+  message: string;
+  type: XTendFeedbackType;
+  closable: boolean;
+  overlay: boolean;
+  ariaLabel: string | null;
+  timestamp: number;
+}
+
+export interface XTendAlertApi {
+  show(message: string, type?: XTendFeedbackType | string, options?: XTendAlertOptions): HTMLElement;
+  success(message: string, options?: XTendAlertOptions): HTMLElement;
+  error(message: string, options?: XTendAlertOptions): HTMLElement;
+  warning(message: string, options?: XTendAlertOptions): HTMLElement;
+  info(message: string, options?: XTendAlertOptions): HTMLElement;
+}
+
+export interface XTendDialogAction {
+  label?: string;
+  action?: string;
+  primary?: boolean;
+  close?: boolean;
+  [key: string]: unknown;
+}
+
+export interface XTendDialogOptions {
+  title?: string;
+  content?: string;
+  overlay?: boolean;
+  actions?: XTendDialogAction[];
+  [key: string]: unknown;
+}
+
+export interface XTendDialogState {
+  id: string;
+  title: string;
+  content: string;
+  hasOverlay: boolean;
+  actions: XTendDialogAction[];
+  timestamp: number;
+  open: boolean;
+}
+
+export interface XTendDialogApi {
+  show(options?: XTendDialogOptions): string;
+  close(dialogId: string): void;
+}
+
+export interface XTendModalOptions extends XTendDialogOptions {}
+
+export interface XTendModalState extends XTendDialogState {}
+
+export interface XTendModalApi {
+  show(options?: XTendModalOptions): string;
+  close(modalId: string): void;
+}
+
+export interface XTendUiState {
+  toasts: XTendToastState[];
+  alerts: XTendAlertState[];
+  dialogs: XTendDialogState[];
+  modals: XTendModalState[];
+}
+
+export interface XTendNamespace {
+  compliance?: XTendComplianceApi;
+  theme?: XTendThemeApi;
+  themeRuntime?: unknown;
+  toast?: XTendToastApi;
+  alert?: XTendAlertApi;
+  dialog?: XTendDialogApi;
+  modal?: XTendModalApi;
+  [key: string]: unknown;
+}
+
+export function initXTendAPI(manifest?: XTendManifest): Promise<void>;
+
+declare global {
+  interface Window {
+    XTend?: XTendNamespace;
+    XTheme?: XTendThemeApi;
+    XToast?: XTendToastApi;
+    XAlert?: XTendAlertApi;
+    XDialog?: XTendDialogApi;
+    XModal?: XTendModalApi;
+    showToast?: XTendToastApi['show'];
+    showAlert?: XTendAlertApi['show'];
+    showDialog?: XTendDialogApi['show'];
+    showModal?: XTendModalApi['show'];
+  }
+
+  interface WindowEventMap {
+    'xtend-api-ready': CustomEvent<XTendApiReadyDetail>;
+  }
+}