@ccslabs/xtend 0.1.0-rc.1

package/xtend-builder/a11y/component-a11y-profile.js

@@ -0,0 +1,314 @@
+const {
+  requireLocalOrScoped
+} = require('../lib/package-resolver');
+const A11Y_COMPONENT_CONTRACT_SCHEMA = 'xtend.a11y.component-contract.v1';
+const A11Y_PROFILE_SCHEMA = 'xtend.a11y.profile.v1';
+const A11Y_TEST_CONTRACT_SCHEMA = 'xtend.a11y.test-contract.v1';
+const SCAFFOLD_A11Y_PROFILE_PLAN_SCHEMA = 'xtend.scaffold.a11y-profile-plan.v1';
+const {
+  SCREENREADER_SIGNALS_SCHEMA: A11Y_SCREENREADER_SIGNALS_SCHEMA,
+  SCREENREADER_SIGNAL_RECORD_SCHEMA: A11Y_SCREENREADER_SIGNAL_RECORD_SCHEMA,
+  createScreenreaderSignalContract
+} = requireLocalOrScoped(
+  __filename,
+  '../../a11y/screenreader-signals',
+  '@ccslabs/xtend/a11y/screenreader-signals'
+);
+const {
+  MOTION_CONTRAST_POLICY_SCHEMA: A11Y_MOTION_CONTRAST_POLICY_SCHEMA,
+  MOTION_POLICY_SCHEMA: A11Y_MOTION_POLICY_SCHEMA,
+  CONTRAST_POLICY_SCHEMA: A11Y_CONTRAST_POLICY_SCHEMA,
+  MOTION_CONTRAST_TEST_SCHEMA: A11Y_MOTION_CONTRAST_TEST_SCHEMA,
+  createMotionContrastPolicy
+} = requireLocalOrScoped(
+  __filename,
+  '../../a11y/motion-contrast-policy',
+  '@ccslabs/xtend/a11y/motion-contrast-policy'
+);
+
+const PROFILE_PRIORITY = [
+  'overlay',
+  'form',
+  'interactive',
+  'routing',
+  'feedback',
+  'media',
+  'stateful',
+  'theme',
+  'display'
+];
+
+const PROFILE_A11Y_RULES = {
+  display: {
+    role: 'region',
+    focusMode: 'none',
+    initialFocus: 'none',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Tab'],
+    ariaStates: ['aria-label'],
+    liveRegion: 'none',
+    screenreaderSignals: ['semantic-region'],
+    reviewChecks: ['semantic-role', 'accessible-name', 'slot-content-readable']
+  },
+  interactive: {
+    role: 'button',
+    focusMode: 'visible-control',
+    initialFocus: 'host',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Enter', 'Space', 'Tab'],
+    ariaStates: ['aria-label', 'aria-pressed', 'aria-disabled'],
+    liveRegion: 'none',
+    screenreaderSignals: ['state-change-announcement'],
+    reviewChecks: ['keyboard-activation', 'focus-visible', 'accessible-name']
+  },
+  stateful: {
+    role: 'region',
+    focusMode: 'stable-host',
+    initialFocus: 'none',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Tab'],
+    ariaStates: ['aria-label', 'aria-busy'],
+    liveRegion: 'polite',
+    screenreaderSignals: ['state-change-summary'],
+    reviewChecks: ['state-change-announcement', 'aria-busy-consistency', 'focus-preservation']
+  },
+  feedback: {
+    role: 'status',
+    focusMode: 'none',
+    initialFocus: 'none',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Escape'],
+    ariaStates: ['aria-label', 'aria-live', 'aria-busy'],
+    liveRegion: 'polite',
+    screenreaderSignals: ['status-announcement', 'dismissal-announcement'],
+    reviewChecks: ['live-region', 'dismissal-path', 'reduced-motion']
+  },
+  overlay: {
+    role: 'dialog',
+    focusMode: 'managed-dialog',
+    initialFocus: 'first-focusable',
+    trapFocus: true,
+    restoreFocus: true,
+    keyboard: ['Escape', 'Tab', 'Shift+Tab'],
+    ariaStates: ['aria-label', 'aria-labelledby', 'aria-modal', 'aria-hidden'],
+    liveRegion: 'none',
+    screenreaderSignals: ['dialog-context', 'focus-return'],
+    reviewChecks: ['focus-trap', 'focus-return', 'aria-modal', 'escape-close']
+  },
+  routing: {
+    role: 'navigation',
+    focusMode: 'route-stable',
+    initialFocus: 'active-route',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Enter', 'Tab', 'ArrowLeft', 'ArrowRight'],
+    ariaStates: ['aria-label', 'aria-current', 'aria-expanded'],
+    liveRegion: 'polite',
+    screenreaderSignals: ['route-change-announcement'],
+    reviewChecks: ['aria-current', 'route-announcement', 'keyboard-navigation']
+  },
+  theme: {
+    role: 'region',
+    focusMode: 'preserve-user-focus',
+    initialFocus: 'none',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Tab'],
+    ariaStates: ['aria-label'],
+    liveRegion: 'none',
+    screenreaderSignals: ['contrast-preservation'],
+    reviewChecks: ['contrast-tokens', 'focus-visible-token', 'no-color-only-state']
+  },
+  form: {
+    role: 'form',
+    focusMode: 'field-order',
+    initialFocus: 'first-invalid-or-first-field',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Enter', 'Tab', 'Shift+Tab'],
+    ariaStates: ['aria-label', 'aria-invalid', 'aria-describedby', 'aria-required'],
+    liveRegion: 'polite',
+    screenreaderSignals: ['validation-error-summary', 'submit-status'],
+    reviewChecks: ['label-association', 'validation-announcement', 'keyboard-submit']
+  },
+  media: {
+    role: 'group',
+    focusMode: 'controls',
+    initialFocus: 'first-control',
+    trapFocus: false,
+    restoreFocus: false,
+    keyboard: ['Space', 'Enter', 'ArrowLeft', 'ArrowRight', 'Tab'],
+    ariaStates: ['aria-label', 'aria-busy', 'aria-valuetext'],
+    liveRegion: 'polite',
+    screenreaderSignals: ['loading-state', 'control-state'],
+    reviewChecks: ['control-labels', 'media-keyboard', 'reduced-motion']
+  }
+};
+
+function unique(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
+function normalizeProfiles(profiles) {
+  const list = Array.isArray(profiles) && profiles.length > 0 ? profiles : ['display'];
+  const normalized = unique(list.map((profile) => String(profile).trim()).filter(Boolean));
+  return normalized.length > 0 ? normalized : ['display'];
+}
+
+function pickPrimaryProfile(profiles) {
+  return PROFILE_PRIORITY.find((profile) => profiles.includes(profile)) || profiles[0] || 'display';
+}
+
+function getRule(profile) {
+  return PROFILE_A11Y_RULES[profile] || PROFILE_A11Y_RULES.display;
+}
+
+function collectProfileRules(profiles, key) {
+  return unique(profiles.flatMap((profile) => getRule(profile)[key] || []));
+}
+
+function createComponentA11yProfile(input = {}, options = {}) {
+  const plan = options.plan || {};
+  const planInput = plan.input || {};
+  const tag = input.tag || planInput.tag || 'x-component';
+  const name = input.name || planInput.name || tag.replace(/^x-/, '');
+  const className = input.className || planInput.className || 'XComponent';
+  const profiles = normalizeProfiles(input.profiles || planInput.profiles);
+  const primaryProfile = pickPrimaryProfile(profiles);
+  const primaryRule = getRule(primaryProfile);
+  const keyboard = collectProfileRules(profiles, 'keyboard');
+  const ariaStates = collectProfileRules(profiles, 'ariaStates');
+  const reviewChecks = collectProfileRules(profiles, 'reviewChecks');
+  const screenreaderSignals = collectProfileRules(profiles, 'screenreaderSignals');
+  const screenreaderSignalContract = createScreenreaderSignalContract({
+    componentRef: tag,
+    primaryProfile,
+    profile: {
+      primaryProfile,
+      screenreader: {
+        liveRegion: primaryRule.liveRegion,
+        signals: screenreaderSignals
+      }
+    }
+  });
+  const motionContrastPolicy = createMotionContrastPolicy({
+    componentRef: tag,
+    primaryProfile,
+    profile: {
+      primaryProfile
+    }
+  });
+  const defaultText = `${className} component`;
+
+  return {
+    schema: A11Y_PROFILE_SCHEMA,
+    planSchema: SCAFFOLD_A11Y_PROFILE_PLAN_SCHEMA,
+    componentContract: A11Y_COMPONENT_CONTRACT_SCHEMA,
+    testContract: A11Y_TEST_CONTRACT_SCHEMA,
+    status: 'scaffold-a11y-required',
+    mode: 'dry-run-a11y-profile',
+    componentRef: tag,
+    name,
+    profiles,
+    primaryProfile,
+    role: primaryRule.role,
+    accessibleName: {
+      source: 'aria-label',
+      required: true,
+      defaultText,
+      fallbackAttribute: 'aria-label'
+    },
+    focusStrategy: {
+      mode: primaryRule.focusMode,
+      initial: primaryRule.initialFocus,
+      trap: primaryRule.trapFocus,
+      restore: primaryRule.restoreFocus,
+      focusVisible: 'required'
+    },
+    keyboard,
+    ariaStates,
+    screenreader: {
+      contract: A11Y_SCREENREADER_SIGNALS_SCHEMA,
+      signalRecordContract: A11Y_SCREENREADER_SIGNAL_RECORD_SCHEMA,
+      liveRegion: primaryRule.liveRegion,
+      signals: screenreaderSignals,
+      signalContract: screenreaderSignalContract,
+      statusRegions: screenreaderSignalContract.statusRegions,
+      errorRegions: screenreaderSignalContract.errorRegions,
+      fabric: screenreaderSignalContract.fabric,
+      announcementRequired: primaryRule.liveRegion !== 'none' || screenreaderSignals.length > 0
+    },
+    motion: {
+      contract: A11Y_MOTION_POLICY_SCHEMA,
+      reducedMotion: 'required',
+      mediaQuery: motionContrastPolicy.motion.mediaQuery,
+      animationPolicy: motionContrastPolicy.motion.animationPolicy,
+      noMotionOnlyState: true,
+      requiredCss: motionContrastPolicy.motion.requiredCss
+    },
+    contrast: {
+      contract: A11Y_CONTRAST_POLICY_SCHEMA,
+      highContrast: 'required',
+      mediaQuery: motionContrastPolicy.contrast.mediaQuery,
+      contrastPolicy: motionContrastPolicy.contrast.contrastPolicy,
+      forcedColorAdjust: motionContrastPolicy.contrast.forcedColorAdjust,
+      focusVisible: 'required',
+      nonColorStatus: 'required',
+      tokenAware: true,
+      systemColorTokens: motionContrastPolicy.contrast.systemColorTokens,
+      requiredCss: motionContrastPolicy.contrast.requiredCss
+    },
+    motionContrast: {
+      contract: A11Y_MOTION_CONTRAST_POLICY_SCHEMA,
+      testContract: A11Y_MOTION_CONTRAST_TEST_SCHEMA,
+      policy: motionContrastPolicy,
+      fabric: motionContrastPolicy.fabric
+    },
+    testRefs: ['components', 'a11y-hydration', 'screenreader-signals', 'motion-contrast', 'references'],
+    testPlan: {
+      schema: A11Y_TEST_CONTRACT_SCHEMA,
+      requiredAssertions: [
+        'static-a11y-profile',
+        'role-or-native-semantics',
+        'accessible-name',
+        'keyboard-contract',
+        'focus-strategy',
+        'aria-state-list',
+        'screenreader-live-region-policy',
+        'screenreader-signals-contract',
+        'announcement-policy',
+        'reduced-motion-policy',
+        'motion-contrast-policy',
+        'forced-colors-policy',
+        'non-color-status-policy'
+      ]
+    },
+    scaffold: {
+      staticGetter: 'xtendScaffoldA11yProfile',
+      manifestKey: 'a11yProfile',
+      requiredFixtureAttributes: ['aria-label'],
+      requiredDocsSections: ['A11y-Profil', 'Screenreader-Signale', 'Motion-und-Contrast-Policy', 'Accessibility und Hydration'],
+      requiredGates: ['components', 'a11y-hydration', 'screenreader-signals', 'motion-contrast', 'references']
+    },
+    reviewRules: reviewChecks
+  };
+}
+
+module.exports = {
+  A11Y_COMPONENT_CONTRACT_SCHEMA,
+  A11Y_PROFILE_SCHEMA,
+  A11Y_MOTION_CONTRAST_POLICY_SCHEMA,
+  A11Y_MOTION_POLICY_SCHEMA,
+  A11Y_CONTRAST_POLICY_SCHEMA,
+  A11Y_MOTION_CONTRAST_TEST_SCHEMA,
+  A11Y_SCREENREADER_SIGNALS_SCHEMA,
+  A11Y_SCREENREADER_SIGNAL_RECORD_SCHEMA,
+  A11Y_TEST_CONTRACT_SCHEMA,
+  PROFILE_A11Y_RULES,
+  SCAFFOLD_A11Y_PROFILE_PLAN_SCHEMA,
+  createComponentA11yProfile
+};

package/xtend-builder/blueprints/README.md

@@ -0,0 +1,105 @@
+# XTend-Scaffold Blueprints
+
+Dieser Bereich enthaelt ab `WP-E03-03` den verbindlichen Komponenten-Blueprint und Artefaktcontract fuer `XTend-Scaffold`.
+
+Der maschinenlesbare Contract liegt in `xtend-builder/blueprints/component-blueprint.contract.js` und nutzt das Schema `xtend.scaffold.component-blueprint.v1`.
+
+## Artefaktmatrix
+
+| Artefakt | Zielpfad | Pflicht | Modus |
+|----------|----------|---------|-------|
+| `component` | `components/<tag>.js` | ja | `write-new` |
+| `docs` | `docs/components/<name>.md` | ja | `write-new` |
+| `tests` | `tests/components/<tag>.component_suite.js` | ja | `write-new` |
+| `fixtures` | `tests/components/fixtures/<tag>.component.html` | ja | `write-new-or-documented-exception` |
+| `types` | `components/<tag>.d.ts` | ja | `write-new-or-documented-exception` |
+| `manifest` | `components/manifest.json` | ja | `patch-plan` |
+| `demo` | `docs/previews/<name>.preview.md` | bedingt | `reference-plan` |
+| `ts-source` | `src/components/<tag>/<tag>.ts` | ja | `write-new` |
+| `ts-contract` | `src/components/<tag>/<tag>.contract.ts` | ja | `write-new` |
+| `ts-rmt` | `src/components/<tag>/<tag>.rmt.ts` | ja | `write-new` |
+| `ts-a11y` | `src/components/<tag>/<tag>.a11y.ts` | ja | `write-new` |
+| `ts-performance` | `src/components/<tag>/<tag>.performance.ts` | ja | `write-new` |
+| `ts-fixture` | `src/components/<tag>/<tag>.fixture.ts` | ja | `write-new` |
+
+## TypeScript Component Blueprint
+
+Seit `WP-E10-07` enthaelt der Komponenten-Blueprint zusaetzlich den Contract `xtend.scaffold.typescript-component-blueprint.v1`. Neue Komponenten werden damit nicht nur als Legacy-kompatibler Runtime-Plan, sondern als TypeScript-first Source-Buendel vorbereitet.
+
+Pflichtbindungen:
+
+- Source Strategy: `xtend.typescript.component-source-strategy.v1`
+- Component Contract: `xtend.component.contract.v2`
+- RMT Component Contract: `xtend.rmt.component-contract.v1`
+- Fabric/Lane Ingestion: `xtend.component.fabric-lane-ingestion.v2`
+- Component Lifecycle Telemetry: `xtend.component.lifecycle-telemetry.v1`
+- Kernel Boundary: `no-rmt-kernel-import-of-xtend-types`
+
+Lokaler Gate:
+
+```bash
+node scripts/run_xtend_tests.js builder-typescript-blueprint --json
+```
+
+## Profilmapping
+
+| Profil | Mindestchecks |
+|--------|---------------|
+| `display` | Registrierung, Manifest, Attribute, Slots, sichtbarer DOM-Vertrag, Hydration-Basis |
+| `interactive` | Display-Basis, Events, Tastatur, Fokus, Labels, Rehydration ohne doppelte Listener |
+| `stateful` | kanonische `xstate` Keys, externe State-Aenderung, Cleanup, SSOT-Grenze |
+| `feedback` | Live-Region, Dismissal, Event-Contract, Timer-Cleanup, Reduced Motion |
+| `overlay` | Open-State, Fokusziel, Escape, Fokus-Rueckgabe, `aria-modal` |
+| `routing` | Navigation, Params/Query, `xstate` Bridge, Route-Events, lokaler Link-Contract |
+| `theme` | Theme-State, CSS Custom Properties, Theme-Event, Legacy-Fassade |
+| `form` | Value, Validation, Labels, Fehlermeldung, Submit-/Change-Events |
+| `media` | Ladezustand, Controls, Tastatur, Fallbacks, Reduced Motion |
+
+## A11y-Pflichtprofil
+
+Seit `ER-WP-23` ist A11y Bestandteil des Blueprints und nicht nur ein Dokumentationshinweis. Jede neue Component-Ausgabe muss die folgenden Contracts durchreichen:
+
+- Component Contract: `xtend.a11y.component-contract.v1`
+- Profil: `xtend.a11y.profile.v1`
+- Test Contract: `xtend.a11y.test-contract.v1`
+- Scaffold Plan: `xtend.scaffold.a11y-profile-plan.v1`
+
+Pflichtartefakte:
+
+- Source: `xtendScaffoldA11yProfile`
+- Docs: Abschnitt `A11y-Profil`
+- Tests: A11y-Profil-, Rollen- und Namensassertions
+- Fixture: `aria-label` plus Hydration-Ergebnis fuer Rolle, Name und Profil
+- Types: `X<Component>A11yProfile`
+- Manifest: `a11yProfile`
+
+## Performance-Pflichtprofil
+
+Seit `ER-WP-21` ist Performance Bestandteil des Blueprints. Jede neue Component-Ausgabe muss die folgenden Contracts durchreichen:
+
+- Scaffold Policy: `xtend.scaffold.performance-policy.v1`
+- Component Profile: `xtend.performance.component-profile.v1`
+- Budget Matrix: `xtend.performance.budget-matrix.v1`
+- Measurement Contract: `xtend.performance.measurement.v1`
+- Regression Gate: `xtend.performance.regression-gate.v1`
+
+Pflichtartefakte:
+
+- Source: `xtendScaffoldPerformanceProfile`
+- Docs: Abschnitte `Performance-Profil` und `Performance-Regeln`
+- Tests: Performance-Profil- und Policy-Assertions
+- Types: `X<Component>PerformanceProfile`
+- Manifest: `performanceProfile`
+
+## Ausnahmeprozess
+
+Ausnahmen sind nur fuer `fixtures`, `types`, `manifest` und `demo` erlaubt. Jede Ausnahme braucht eine explizite Begruendung im Worklog, in der Komponentendoku oder in der Suite. Leere Testdateien, stillschweigend ausgelassene Manifest-Eintraege und undokumentierte Typ-Luecken sind nicht erlaubt.
+
+## Lokale Contract-Ausgabe
+
+```bash
+node xtend-builder/scaffold.js blueprint
+node xtend-builder/scaffold.js blueprint --json
+```
+
+Grenze in `WP-E03-03`: Der Blueprint definiert den Contract, erzeugt aber noch keine Produktivdateien. Generator-Grundgeruest und Template-Ladepfad folgen in `WP-E03-04`.

package/xtend-builder/blueprints/component-blueprint.contract.d.ts

@@ -0,0 +1,16 @@
+import type { XtendBuilderArtifactContract, XtendBuilderBlueprintContract, XtendBuilderConstant, XtendBuilderRecord } from '../builder-public-types';
+
+export declare const ARTIFACT_MATRIX: XtendBuilderArtifactContract[];
+export declare const A11Y_PROFILE_REQUIREMENTS: XtendBuilderConstant<XtendBuilderRecord>;
+export declare const COMPONENT_BLUEPRINT_SCHEMA: string;
+export declare const TYPESCRIPT_BLUEPRINT_REQUIREMENTS: XtendBuilderConstant<XtendBuilderRecord>;
+export declare const TYPESCRIPT_COMPONENT_BLUEPRINT_SCHEMA: string;
+export declare const COMPONENT_FABRIC_LANE_INGESTION_SCHEMA: string;
+export declare const COMPONENT_LIFECYCLE_TELEMETRY_SCHEMA: string;
+export declare const EXCEPTION_POLICY: XtendBuilderConstant<XtendBuilderRecord>;
+export declare const NAMING_CONTRACT: XtendBuilderConstant<XtendBuilderRecord>;
+export declare const PERFORMANCE_POLICY_REQUIREMENTS: XtendBuilderConstant<XtendBuilderRecord>;
+export declare const PROFILE_CHECKS: XtendBuilderRecord[];
+export declare function getArtifactContract(id: string): XtendBuilderArtifactContract | null;
+export declare function getComponentBlueprintContract(): XtendBuilderBlueprintContract;
+export declare function getProfileContract(profile: string): XtendBuilderRecord | null;