@nice2dev/ui-core 1.0.10

package/dist/core/a11y-advanced.d.ts

@@ -0,0 +1,157 @@
+/**
+ * a11y-advanced.ts — Advanced accessibility features.
+ *
+ * Voice control, screen reader optimizations, cognitive accessibility,
+ * and WCAG 2.2 AAA compliance utilities.
+ */
+export interface VoiceCommand {
+    phrase: string | RegExp;
+    action: (matches: string[], transcript: string) => void;
+    description?: string;
+}
+export interface VoiceControlOptions {
+    language?: string;
+    continuous?: boolean;
+    interimResults?: boolean;
+    commands?: VoiceCommand[];
+    onTranscript?: (text: string, isFinal: boolean) => void;
+    onError?: (error: string) => void;
+}
+export interface VoiceControlApi {
+    isListening: boolean;
+    isSupported: boolean;
+    start: () => void;
+    stop: () => void;
+    transcript: string;
+}
+/**
+ * Hook for voice-controlled UI interaction.
+ *
+ * Usage:
+ *   const { isListening, start, stop } = useVoiceControl({
+ *     commands: [
+ *       { phrase: /open (.+)/i, action: ([, name]) => openPage(name) },
+ *       { phrase: "scroll down", action: () => window.scrollBy(0, 300) },
+ *     ],
+ *   });
+ */
+export declare function useVoiceControl(options?: VoiceControlOptions): VoiceControlApi;
+export interface LiveRegionOptions {
+    politeness?: 'polite' | 'assertive' | 'off';
+    atomic?: boolean;
+    relevant?: 'additions' | 'removals' | 'text' | 'all';
+    clearAfterMs?: number;
+}
+/**
+ * Hook to announce dynamic content to screen readers via ARIA live regions.
+ */
+export declare function useLiveAnnouncement(options?: LiveRegionOptions): {
+    message: string;
+    announce: (text: string) => void;
+    regionProps: {
+        role: "status";
+        'aria-live': "off" | "polite" | "assertive";
+        'aria-atomic': boolean;
+        'aria-relevant': "text" | "all" | "additions" | "removals" | "additions text";
+        style: {
+            position: "absolute";
+            width: number;
+            height: number;
+            overflow: "hidden";
+            clip: string;
+            whiteSpace: "nowrap";
+        };
+    };
+};
+/**
+ * Screen reader-friendly route announcement.
+ */
+export declare function useRouteAnnouncement(): {
+    announcePageChange: (pageTitle: string) => void;
+    regionProps: {
+        role: "status";
+        'aria-live': "off" | "polite" | "assertive";
+        'aria-atomic': boolean;
+        'aria-relevant': "text" | "all" | "additions" | "removals" | "additions text";
+        style: {
+            position: "absolute";
+            width: number;
+            height: number;
+            overflow: "hidden";
+            clip: string;
+            whiteSpace: "nowrap";
+        };
+    };
+    message: string;
+};
+/**
+ * Enhanced focus management for complex widgets.
+ */
+export declare function useFocusManagement(): {
+    containerRef: import("react").RefObject<HTMLElement>;
+    focusFirst: () => void;
+    focusElement: (selector: string) => void;
+    getFocusableElements: () => HTMLElement[];
+};
+export interface CognitiveAccessibilityOptions {
+    /** Simplify interface by hiding non-essential elements. */
+    simplifiedMode?: boolean;
+    /** Increase spacing between interactive elements. */
+    increasedSpacing?: boolean;
+    /** Show reading guides (horizontal line that follows cursor). */
+    readingGuide?: boolean;
+    /** Highlight focused element with thick outline. */
+    enhancedFocus?: boolean;
+    /** Reduce animation motion. */
+    reduceMotion?: boolean;
+    /** Show text labels alongside icons. */
+    iconLabels?: boolean;
+    /** Larger click targets (56px minimum). */
+    largeTargets?: boolean;
+    /** Dyslexia-friendly font. */
+    dyslexiaFont?: boolean;
+    /** Line spacing multiplier (1.0 - 3.0). */
+    lineSpacing?: number;
+    /** Word spacing multiplier (1.0 - 3.0). */
+    wordSpacing?: number;
+}
+/**
+ * Hook for cognitive accessibility features.
+ *
+ * Returns CSS class names and inline styles to apply to the app root.
+ */
+export declare function useCognitiveAccessibility(options?: CognitiveAccessibilityOptions): {
+    settings: {
+        simplifiedMode?: boolean;
+        increasedSpacing?: boolean;
+        readingGuide?: boolean;
+        enhancedFocus?: boolean;
+        reduceMotion?: boolean;
+        iconLabels?: boolean;
+        largeTargets?: boolean;
+        dyslexiaFont?: boolean;
+        lineSpacing?: number;
+        wordSpacing?: number;
+    };
+    updateSetting: <K extends keyof CognitiveAccessibilityOptions>(key: K, value: CognitiveAccessibilityOptions[K]) => void;
+    css: string;
+    rootClasses: string;
+    rootStyle: Record<string, string>;
+};
+export interface WCAGCheckResult {
+    rule: string;
+    level: 'A' | 'AA' | 'AAA';
+    passed: boolean;
+    message: string;
+    element?: string;
+}
+/**
+ * Check color contrast against WCAG AAA requirements.
+ * AAA requires 7:1 for normal text, 4.5:1 for large text.
+ */
+export declare function checkContrastAAA(foreground: string, background: string, isLargeText?: boolean): WCAGCheckResult;
+/**
+ * Run a comprehensive WCAG 2.2 AAA audit on the current document.
+ */
+export declare function auditWCAG22AAA(): WCAGCheckResult[];
+//# sourceMappingURL=a11y-advanced.d.ts.map

package/dist/core/a11y-advanced.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-advanced.d.ts","sourceRoot":"","sources":["../../src/core/a11y-advanced.ts"],"names":[],"mappings":"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"}

package/dist/core/a11y.d.ts

@@ -0,0 +1,299 @@
+import React from 'react';
+export interface NiceA11yConfig {
+    /** Announce state changes to screen readers (default: true) */
+    announceChanges: boolean;
+    /** Reduce motion for users with vestibular motion disorders (default: 'auto' = respect OS setting) */
+    reduceMotion: 'auto' | 'always' | 'never';
+    /** High contrast mode (default: 'auto' = respect OS setting) */
+    highContrast: 'auto' | 'always' | 'never';
+    /** Focus visible style: 'auto' uses :focus-visible, 'always' shows on any focus */
+    focusStyle: 'auto' | 'always';
+    /** Whether keyboard shortcuts are enabled (default: true) */
+    keyboardShortcuts: boolean;
+    /** Minimum touch target size in px (WCAG 2.5.8 — 24px minimum) */
+    minTouchTarget: number;
+}
+interface A11yContextValue {
+    config: NiceA11yConfig;
+    announce: (message: string, priority?: 'polite' | 'assertive') => void;
+    prefersReducedMotion: boolean;
+    prefersHighContrast: boolean;
+}
+export interface NiceA11yProviderProps {
+    config?: Partial<NiceA11yConfig>;
+    children: React.ReactNode;
+}
+export declare const NiceA11yProvider: React.FC<NiceA11yProviderProps>;
+export declare function useNiceA11y(): A11yContextValue;
+/** Build aria-describedby from helper/error text ids */
+export declare function buildAriaDescribedBy(...ids: (string | undefined | null | false)[]): string | undefined;
+/** Build standard form field ARIA attributes */
+export declare function buildFormFieldAria(props: {
+    id: string;
+    label?: string;
+    error?: string;
+    helperText?: string;
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+}): Record<string, string | boolean | undefined>;
+export type ArrowDirection = 'horizontal' | 'vertical' | 'both' | 'grid';
+export interface UseRovingTabIndexOptions {
+    /** Direction of arrow key navigation */
+    direction: ArrowDirection;
+    /** Wrap around from last to first and vice versa (default: true) */
+    wrap?: boolean;
+    /** Selector for focusable items within the container */
+    itemSelector?: string;
+}
+/**
+ * Roving tabindex for keyboard navigation in composite widgets
+ * (toolbars, radio groups, menu bars, tab lists, grids).
+ *
+ * Only one item has tabIndex=0 (the active one); others have tabIndex=-1.
+ * Arrow keys move focus between items.
+ */
+export declare function useRovingTabIndex(containerRef: React.RefObject<HTMLElement | null>, options: UseRovingTabIndexOptions): void;
+/** Return focus to the element that was focused before the component mounted */
+export declare function useRestoreFocus(active: boolean): void;
+/** VisuallyHidden component for screen-reader-only text */
+export declare const NiceVisuallyHidden: React.FC<{
+    children: React.ReactNode;
+    as?: keyof JSX.IntrinsicElements;
+}>;
+export interface NiceSkipLinkProps {
+    /** Target element id (without #) */
+    targetId: string;
+    /** Link text (default: 'Skip to main content') */
+    children?: React.ReactNode;
+}
+export declare const NiceSkipLink: React.FC<NiceSkipLinkProps>;
+/** Standard keyboard shortcut definition for a control */
+export interface KeyboardShortcut {
+    /** Key combination (e.g., 'Enter', 'Ctrl+S', 'Escape') */
+    key: string;
+    /** Description of what the shortcut does */
+    description: string;
+    /** i18n key for the description */
+    descriptionKey?: string;
+    /** Modifier keys required */
+    modifiers?: ('ctrl' | 'alt' | 'shift' | 'meta')[];
+}
+/** Common keyboard shortcuts used across controls */
+export declare const COMMON_SHORTCUTS: {
+    readonly submit: {
+        readonly key: "Enter";
+        readonly description: "Submit / Confirm";
+        readonly descriptionKey: "shortcuts.submit";
+    };
+    readonly cancel: {
+        readonly key: "Escape";
+        readonly description: "Cancel / Close";
+        readonly descriptionKey: "shortcuts.cancel";
+    };
+    readonly clear: {
+        readonly key: "Delete";
+        readonly description: "Clear value";
+        readonly descriptionKey: "shortcuts.clear";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly moveUp: {
+        readonly key: "ArrowUp";
+        readonly description: "Move up";
+        readonly descriptionKey: "shortcuts.moveUp";
+    };
+    readonly moveDown: {
+        readonly key: "ArrowDown";
+        readonly description: "Move down";
+        readonly descriptionKey: "shortcuts.moveDown";
+    };
+    readonly moveLeft: {
+        readonly key: "ArrowLeft";
+        readonly description: "Move left";
+        readonly descriptionKey: "shortcuts.moveLeft";
+    };
+    readonly moveRight: {
+        readonly key: "ArrowRight";
+        readonly description: "Move right";
+        readonly descriptionKey: "shortcuts.moveRight";
+    };
+    readonly first: {
+        readonly key: "Home";
+        readonly description: "Go to first";
+        readonly descriptionKey: "shortcuts.first";
+    };
+    readonly last: {
+        readonly key: "End";
+        readonly description: "Go to last";
+        readonly descriptionKey: "shortcuts.last";
+    };
+    readonly pageUp: {
+        readonly key: "PageUp";
+        readonly description: "Page up";
+        readonly descriptionKey: "shortcuts.pageUp";
+    };
+    readonly pageDown: {
+        readonly key: "PageDown";
+        readonly description: "Page down";
+        readonly descriptionKey: "shortcuts.pageDown";
+    };
+    readonly selectAll: {
+        readonly key: "A";
+        readonly description: "Select all";
+        readonly descriptionKey: "shortcuts.selectAll";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly toggleSelect: {
+        readonly key: "Space";
+        readonly description: "Toggle selection";
+        readonly descriptionKey: "shortcuts.toggleSelect";
+    };
+    readonly undo: {
+        readonly key: "Z";
+        readonly description: "Undo";
+        readonly descriptionKey: "shortcuts.undo";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly redo: {
+        readonly key: "Y";
+        readonly description: "Redo";
+        readonly descriptionKey: "shortcuts.redo";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly copy: {
+        readonly key: "C";
+        readonly description: "Copy";
+        readonly descriptionKey: "shortcuts.copy";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly paste: {
+        readonly key: "V";
+        readonly description: "Paste";
+        readonly descriptionKey: "shortcuts.paste";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly cut: {
+        readonly key: "X";
+        readonly description: "Cut";
+        readonly descriptionKey: "shortcuts.cut";
+        readonly modifiers: readonly ["ctrl"];
+    };
+    readonly edit: {
+        readonly key: "Enter";
+        readonly description: "Edit cell";
+        readonly descriptionKey: "shortcuts.edit";
+    };
+    readonly tab: {
+        readonly key: "Tab";
+        readonly description: "Next cell";
+        readonly descriptionKey: "shortcuts.tab";
+    };
+    readonly shiftTab: {
+        readonly key: "Tab";
+        readonly description: "Previous cell";
+        readonly descriptionKey: "shortcuts.shiftTab";
+        readonly modifiers: readonly ["shift"];
+    };
+    readonly open: {
+        readonly key: "ArrowDown";
+        readonly description: "Open dropdown";
+        readonly descriptionKey: "shortcuts.open";
+    };
+    readonly close: {
+        readonly key: "Escape";
+        readonly description: "Close popup";
+        readonly descriptionKey: "shortcuts.close";
+    };
+    readonly increment: {
+        readonly key: "ArrowUp";
+        readonly description: "Increase value";
+        readonly descriptionKey: "shortcuts.increment";
+    };
+    readonly decrement: {
+        readonly key: "ArrowDown";
+        readonly description: "Decrease value";
+        readonly descriptionKey: "shortcuts.decrement";
+    };
+    readonly incrementBig: {
+        readonly key: "PageUp";
+        readonly description: "Increase by 10";
+        readonly descriptionKey: "shortcuts.incrementBig";
+    };
+    readonly decrementBig: {
+        readonly key: "PageDown";
+        readonly description: "Decrease by 10";
+        readonly descriptionKey: "shortcuts.decrementBig";
+    };
+};
+/** Format a keyboard shortcut for display */
+export declare function formatShortcut(shortcut: KeyboardShortcut): string;
+/** Check if a keyboard event matches a shortcut */
+export declare function matchesShortcut(e: React.KeyboardEvent | KeyboardEvent, shortcut: KeyboardShortcut): boolean;
+export interface NiceKeyboardHintProps {
+    /** Array of keyboard shortcuts to display */
+    shortcuts: KeyboardShortcut[];
+    /** Position of the tooltip */
+    position?: 'top' | 'bottom' | 'left' | 'right';
+    /** Custom trigger icon (default: ?) */
+    icon?: React.ReactNode;
+    /** Size of the hint trigger */
+    size?: 'sm' | 'md';
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * A small question mark icon that shows keyboard shortcuts on hover.
+ * Use this to inform users about available keyboard interactions.
+ */
+export declare const NiceKeyboardHint: React.FC<NiceKeyboardHintProps>;
+export interface UseSubmitOnEnterOptions {
+    /** Enable submit on Enter (default: false) */
+    enabled?: boolean;
+    /** Callback to execute on Enter */
+    onSubmit?: () => void;
+    /** Prevent default behavior (default: true) */
+    preventDefault?: boolean;
+    /** Require Ctrl+Enter instead of just Enter (default: false) */
+    requireCtrl?: boolean;
+    /** Skip if in a textarea (default: true) */
+    skipTextarea?: boolean;
+}
+/**
+ * Hook to handle Enter key as submit trigger.
+ * Returns a keydown handler to attach to the control.
+ */
+export declare function useSubmitOnEnter(options?: UseSubmitOnEnterOptions): (e: React.KeyboardEvent) => void;
+export interface UseAccessibleClickOptions {
+    /** Click handler invoked on mouse click, Enter, or Space */
+    onClick?: (e: React.SyntheticEvent) => void;
+    /** Disable interaction (default: false) */
+    disabled?: boolean;
+    /** ARIA role to apply (default: 'button') */
+    role?: string;
+    /** Override tabIndex (default: 0 when enabled, -1 when disabled) */
+    tabIndex?: number;
+    /** Trigger on Space key in addition to Enter (default: true) */
+    triggerOnSpace?: boolean;
+}
+export interface AccessibleClickProps {
+    role: string;
+    tabIndex: number;
+    onClick: (e: React.MouseEvent) => void;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+    'aria-disabled'?: boolean;
+}
+/**
+ * Returns props to attach to a non-semantic element (e.g. <div>) to make it
+ * keyboard-accessible — handles Enter / Space activation, role, tabIndex,
+ * and respects the disabled state. Prefer a real <button> when possible;
+ * use this hook only when semantic elements are not feasible.
+ *
+ * Example:
+ * ```tsx
+ * const clickProps = useAccessibleClick({ onClick: handleSelect });
+ * return <div {...clickProps}>Click me</div>;
+ * ```
+ */
+export declare function useAccessibleClick(options?: UseAccessibleClickOptions): AccessibleClickProps;
+export {};
+//# sourceMappingURL=a11y.d.ts.map

package/dist/core/a11y.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y.d.ts","sourceRoot":"","sources":["../../src/core/a11y.tsx"],"names":[],"mappings":"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"}

package/dist/core/access-control.d.ts

@@ -0,0 +1,59 @@
+import React from 'react';
+import type { NiceAccessMode } from './types';
+export type { NiceAccessMode };
+export interface NiceAccessPermissions {
+    /** Default access mode for all components under this provider */
+    defaultMode?: NiceAccessMode;
+    /** Per-component overrides: componentId → accessMode */
+    components?: Record<string, NiceAccessMode>;
+    /** Per-field overrides: "component.field" → accessMode */
+    fields?: Record<string, NiceAccessMode>;
+}
+export interface NiceAccessControlProps {
+    permissions: NiceAccessPermissions;
+    children: React.ReactNode;
+}
+/**
+ * Provider that sets access control policies for all NiceToDev components
+ * within its tree. Components auto-check permissions via `useNiceAccessMode`.
+ *
+ * @example
+ * ```tsx
+ * <NiceAccessControl permissions={{
+ *   defaultMode: 'readOnly',
+ *   components: { 'userForm': 'full', 'adminGrid': 'hidden' },
+ *   fields: { 'userForm.email': 'disabled' },
+ * }}>
+ *   <App />
+ * </NiceAccessControl>
+ * ```
+ */
+export declare const NiceAccessControl: React.FC<NiceAccessControlProps>;
+/**
+ * Hook to resolve the effective access mode for the current component.
+ * Merges provider-level and prop-level access settings.
+ *
+ * @param propAccessMode - Explicit prop passed to the component (highest priority)
+ * @param componentId - Optional ID to look up in provider permissions
+ * @param fieldId - Optional field-level ID for form field granularity
+ * @returns The resolved NiceAccessMode
+ *
+ * @example
+ * ```tsx
+ * const accessMode = useNiceAccessMode(props.accessMode, props.id);
+ * if (accessMode === 'hidden') return null;
+ * const isReadOnly = accessMode === 'readOnly' || accessMode === 'disabled';
+ * ```
+ */
+export declare function useNiceAccessMode(propAccessMode?: NiceAccessMode, componentId?: string, fieldId?: string): NiceAccessMode;
+/**
+ * Utility: apply access mode effects on HTML attributes.
+ * Returns props to spread onto interactive elements.
+ */
+export declare function accessModeAttrs(mode: NiceAccessMode): {
+    disabled?: boolean;
+    readOnly?: boolean;
+    'aria-disabled'?: boolean;
+    tabIndex?: number;
+};
+//# sourceMappingURL=access-control.d.ts.map

package/dist/core/access-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-control.d.ts","sourceRoot":"","sources":["../../src/core/access-control.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAM9C,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACzC;AAaD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,qBAAqB,CAAC;IACnC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAmB9D,CAAC;AAIF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,cAAc,CAAC,EAAE,cAAc,EAC/B,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,MAAM,GACf,cAAc,CAOhB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG;IACrD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CASA"}