@nice2dev/ui-core 1.0.10

package/dist/core/traceless.d.ts

@@ -0,0 +1,461 @@
+/**
+ * @fileoverview Traceless™ — Zero-Trace Privacy Architecture
+ * @module @nice2dev/ui/core/traceless
+ *
+ * Traceless™ is OmniVerk's flagship privacy feature that allows complete control
+ * over client-side storage (cookies, localStorage, sessionStorage).
+ *
+ * "Żadnych śladów. Żadnych cookies. Żadnego localStorage. Żadnego bannera. Traceless."
+ *
+ * @example
+ * ```tsx
+ * import { TracelessProvider, useTracelessPolicy, StorageAdapter } from '@nice2dev/ui';
+ *
+ * // In your app root:
+ * <TracelessProvider>
+ *   <App />
+ * </TracelessProvider>
+ *
+ * // In components:
+ * const { mode, canUseCookies, canUseLocalStorage } = useTracelessPolicy();
+ * const storage = useStorageAdapter();
+ * storage.set('key', 'value'); // Automatically respects policy
+ * ```
+ */
+/**
+ * Privacy storage modes from most private to most permissive.
+ *
+ * | Mode       | Cookies | localStorage | sessionStorage | Consent Banner |
+ * |------------|---------|--------------|----------------|----------------|
+ * | traceless  | ❌      | ❌           | ❌             | ❌ Never       |
+ * | ephemeral  | ❌      | ❌           | ✅             | ❌ Never       |
+ * | private    | 1 auth  | ❌           | ✅             | ❌ Exempt      |
+ * | balanced   | ❌      | ✅           | ✅             | ⚠️ Maybe       |
+ * | full       | ✅      | ✅           | ✅             | ✅ Required    |
+ * | custom     | Config  | Config       | Config         | Config         |
+ */
+export type TracelessMode = 'traceless' | 'ephemeral' | 'private' | 'balanced' | 'full' | 'custom';
+/**
+ * Per-control storage mode configuration.
+ */
+export type ControlStorageMode = 'traceless' | 'ephemeral' | 'persistent' | 'auto';
+/**
+ * Main policy interface for Traceless system.
+ * Three independent flags for granular control.
+ */
+export interface ITracelessPolicy {
+    /** Whether cookies are allowed (any cookies) */
+    cookiesAllowed: boolean;
+    /** Whether localStorage is allowed */
+    localStorageAllowed: boolean;
+    /** Whether sessionStorage is allowed */
+    sessionStorageAllowed: boolean;
+    /** Whether only strictly necessary auth cookie is allowed (httpOnly) */
+    strictAuthCookieOnly: boolean;
+    /** The effective mode derived from flags */
+    effectiveMode: TracelessMode;
+    /** Source of the policy (instance, tenant, group, user) */
+    source: TracelessPolicySource;
+    /** Whether consent banner should be shown */
+    requiresConsentBanner: boolean;
+    /** Timestamp when policy was resolved */
+    resolvedAt: number;
+    /** Policy version for cache invalidation */
+    version: string;
+}
+/**
+ * Source hierarchy for policy resolution.
+ * Lower sources cannot exceed permissions of higher sources.
+ */
+export type TracelessPolicySource = 'instance' | 'tenant' | 'group' | 'user' | 'control' | 'default';
+/**
+ * Instance-level ceiling configuration.
+ * Sets the maximum permissions any tenant/user can have.
+ */
+export interface TracelessInstanceCeiling {
+    /** Maximum cookie permission for all tenants */
+    maxCookies: boolean;
+    /** Maximum localStorage permission for all tenants */
+    maxLocalStorage: boolean;
+    /** Maximum sessionStorage permission for all tenants */
+    maxSessionStorage: boolean;
+    /** Instance-wide default mode */
+    defaultMode: TracelessMode;
+    /** Allow tenants to override? */
+    allowTenantOverride: boolean;
+    /** Instance ID for audit */
+    instanceId: string;
+}
+/**
+ * Tenant-level policy configuration.
+ */
+export interface TracelessTenantPolicy {
+    tenantId: string;
+    /** Policy mode (cannot exceed instance ceiling) */
+    mode: TracelessMode;
+    /** Custom overrides */
+    customPolicy?: Partial<ITracelessPolicy>;
+    /** Allow user groups to override? */
+    allowGroupOverride: boolean;
+    /** Allow individual users to override? */
+    allowUserOverride: boolean;
+    /** Last updated timestamp */
+    updatedAt: number;
+    /** Updated by user ID */
+    updatedBy?: string;
+}
+/**
+ * User group policy.
+ */
+export interface TracelessGroupPolicy {
+    groupId: string;
+    tenantId: string;
+    /** Policy mode (cannot exceed tenant policy) */
+    mode: TracelessMode;
+    /** Allow users in this group to self-lockdown? */
+    allowUserLockdown: boolean;
+}
+/**
+ * User self-lockdown configuration.
+ * Users can only INCREASE privacy, never decrease it.
+ */
+export interface TracelessUserPreference {
+    userId: string;
+    /** User's preferred mode (must be >= group mode in privacy) */
+    preferredMode: TracelessMode;
+    /** Explicit overrides (can only restrict, not permit) */
+    restrictCookies?: boolean;
+    restrictLocalStorage?: boolean;
+    restrictSessionStorage?: boolean;
+    /** When user set this preference */
+    setAt: number;
+}
+/**
+ * Module storage requirements declaration.
+ */
+export interface ModuleStorageRequirement {
+    moduleId: string;
+    moduleName: string;
+    /** Minimum required for full functionality */
+    minSessionStorage: boolean;
+    minLocalStorage: boolean;
+    minCookies: boolean;
+    /** Features that degrade without storage */
+    degradedFeatures: DegradedFeature[];
+}
+/**
+ * Feature degradation info for UX warnings.
+ */
+export interface DegradedFeature {
+    featureId: string;
+    featureName: string;
+    /** What's affected */
+    degradationType: 'disabled' | 'limited' | 'no-persistence' | 'reset-on-refresh';
+    /** User-friendly message */
+    userMessage: string;
+    /** Locale key for i18n */
+    messageKey: string;
+}
+/**
+ * Audit entry for policy changes.
+ */
+export interface TracelessAuditEntry {
+    id: string;
+    timestamp: number;
+    action: 'policy_changed' | 'user_lockdown' | 'admin_override' | 'api_access';
+    actorId: string;
+    actorType: 'system' | 'admin' | 'user';
+    previousMode?: TracelessMode;
+    newMode?: TracelessMode;
+    previousPolicy?: Partial<ITracelessPolicy>;
+    newPolicy?: Partial<ITracelessPolicy>;
+    ipAddress?: string;
+    userAgent?: string;
+    reason?: string;
+    source: TracelessPolicySource;
+    tenantId?: string;
+    groupId?: string;
+    userId?: string;
+}
+/**
+ * Default policy - most private out of the box (traceless).
+ */
+export declare const DEFAULT_TRACELESS_POLICY: ITracelessPolicy;
+/**
+ * Policy presets for each mode.
+ */
+export declare const TRACELESS_MODE_PRESETS: Record<TracelessMode, Omit<ITracelessPolicy, 'source' | 'resolvedAt' | 'version'>>;
+/**
+ * Privacy level ordering (lower index = more private).
+ */
+export declare const PRIVACY_LEVEL_ORDER: TracelessMode[];
+/**
+ * Compares two modes and returns the more private one.
+ */
+export declare function getMorePrivateMode(a: TracelessMode, b: TracelessMode): TracelessMode;
+/**
+ * Checks if mode A is at least as private as mode B.
+ */
+export declare function isAtLeastAsPrivate(a: TracelessMode, b: TracelessMode): boolean;
+/**
+ * Resolves effective policy from hierarchy.
+ * Instance ceiling → Tenant policy → Group policy → User preference
+ */
+export declare function resolveTracelessPolicy(instanceCeiling: TracelessInstanceCeiling, tenantPolicy?: TracelessTenantPolicy, groupPolicy?: TracelessGroupPolicy, userPreference?: TracelessUserPreference): ITracelessPolicy;
+/**
+ * Derives the effective mode from policy flags.
+ */
+export declare function deriveMode(policy: Pick<ITracelessPolicy, 'cookiesAllowed' | 'localStorageAllowed' | 'sessionStorageAllowed' | 'strictAuthCookieOnly'>): TracelessMode;
+/**
+ * Determines if consent banner should be shown.
+ */
+export declare function shouldShowConsentBanner(policy: ITracelessPolicy): boolean;
+/**
+ * Storage backend type.
+ */
+export type StorageBackendType = 'memory' | 'session' | 'local';
+/**
+ * Unified storage adapter that respects Traceless policy.
+ * Gracefully degrades based on what's available.
+ */
+export declare class StorageAdapter {
+    private policy;
+    private namespace;
+    private defaultBackend;
+    constructor(policy: ITracelessPolicy, namespace?: string, defaultBackend?: StorageBackendType);
+    /**
+     * Gets the appropriate storage backend based on policy.
+     */
+    private getBackend;
+    /**
+     * Gets the prefixed key.
+     */
+    private getKey;
+    /**
+     * Gets a value from storage.
+     */
+    get<T = string>(key: string, preferredBackend?: StorageBackendType): T | null;
+    /**
+     * Sets a value in storage.
+     * Silently no-ops if storage is not available (graceful degradation).
+     */
+    set(key: string, value: unknown, preferredBackend?: StorageBackendType): boolean;
+    /**
+     * Removes a value from storage.
+     */
+    remove(key: string, preferredBackend?: StorageBackendType): boolean;
+    /**
+     * Clears all namespaced values from storage.
+     */
+    clear(preferredBackend?: StorageBackendType): void;
+    /**
+     * Gets all keys in the namespace.
+     */
+    keys(preferredBackend?: StorageBackendType): string[];
+    /**
+     * Checks if a key exists.
+     */
+    has(key: string, preferredBackend?: StorageBackendType): boolean;
+    /**
+     * Gets info about current storage capabilities.
+     */
+    getCapabilities(): StorageCapabilities;
+    /**
+     * Gets the actual backend type being used.
+     */
+    private getActualBackendType;
+    /**
+     * Updates the policy (e.g., after user changes preferences).
+     */
+    updatePolicy(policy: ITracelessPolicy): void;
+}
+/**
+ * Storage capabilities info.
+ */
+export interface StorageCapabilities {
+    canUseCookies: boolean;
+    canUseLocalStorage: boolean;
+    canUseSessionStorage: boolean;
+    canPersist: boolean;
+    effectiveMode: TracelessMode;
+    actualBackend: StorageBackendType;
+}
+/**
+ * Props for traceless-aware controls.
+ */
+export interface TracelessControlProps {
+    /**
+     * Whether this control can use cookies.
+     * Can only restrict (false), not permit (true) if policy forbids.
+     * @default false
+     */
+    cookies?: boolean;
+    /**
+     * Whether this control can use localStorage.
+     * Can only restrict (false), not permit (true) if policy forbids.
+     * @default false
+     */
+    localStorage?: boolean;
+    /**
+     * Storage mode shorthand.
+     * - 'traceless': All storage off
+     * - 'ephemeral': sessionStorage only
+     * - 'persistent': localStorage OK
+     * - 'auto': Respect global policy (default)
+     * @default 'auto'
+     */
+    storageMode?: ControlStorageMode;
+}
+/**
+ * Resolves control-level storage permissions.
+ */
+export declare function resolveControlStoragePermissions(globalPolicy: ITracelessPolicy, controlProps: TracelessControlProps): ITracelessPolicy;
+/**
+ * Generates a compliance report for the current traceless configuration.
+ */
+export declare function generateTracelessComplianceReport(policy: ITracelessPolicy, instanceId: string, tenantId?: string): TracelessComplianceReport;
+/**
+ * Compliance report structure.
+ */
+export interface TracelessComplianceReport {
+    generatedAt: string;
+    instanceId: string;
+    tenantId?: string;
+    effectiveMode: TracelessMode;
+    cookies: {
+        count: number;
+        allowed: boolean;
+        strictAuthOnly: boolean;
+        thirdParty: boolean;
+        tracking: boolean;
+    };
+    localStorage: {
+        bytesUsed: number;
+        allowed: boolean;
+        keysCount: number;
+    };
+    sessionStorage: {
+        bytesUsed: number;
+        allowed: boolean;
+        keysCount: number;
+    };
+    consentBanner: {
+        required: boolean;
+        shown: boolean;
+    };
+    compliance: {
+        ePrivacyCompliant: boolean;
+        gdprCompliant: boolean;
+        pecrCompliant: boolean;
+    };
+    statement: string;
+}
+/**
+ * Badge display info for TracelessBadge component.
+ */
+export interface TracelessBadgeInfo {
+    mode: TracelessMode;
+    icon: string;
+    color: string;
+    label: string;
+    tooltip: string;
+    cssClass: string;
+}
+/**
+ * Gets badge display info for the current mode.
+ */
+export declare function getTracelessBadgeInfo(policy: ITracelessPolicy): TracelessBadgeInfo;
+/**
+ * Graceful degradation information for components.
+ */
+export interface GracefulDegradationInfo {
+    /** Whether persistence is available */
+    canPersist: boolean;
+    /** Whether session storage is available */
+    canSession: boolean;
+    /** Warning message to show (if any) */
+    warningMessage?: string;
+    /** Locale key for warning */
+    warningKey?: string;
+}
+/**
+ * Gets graceful degradation info for a specific use case.
+ */
+export declare function getGracefulDegradationInfo(policy: ITracelessPolicy, useCase: 'preferences' | 'draft' | 'history' | 'auth' | 'grid-state'): GracefulDegradationInfo;
+/**
+ * HTTP header name for storage policy.
+ */
+export declare const TRACELESS_POLICY_HEADER = "X-OmniVerk-Storage-Policy";
+/**
+ * Parses policy from HTTP header.
+ */
+export declare function parsePolicyFromHeader(headerValue: string): TracelessMode | null;
+/**
+ * Creates policy header value.
+ */
+export declare function createPolicyHeader(policy: ITracelessPolicy): string;
+/**
+ * Creates a new StorageAdapter with the given policy.
+ */
+export declare function createStorageAdapter(policy: ITracelessPolicy, namespace?: string): StorageAdapter;
+/**
+ * Creates the most restrictive instance ceiling (for healthcare, etc.).
+ */
+export declare function createRestrictiveInstanceCeiling(instanceId: string): TracelessInstanceCeiling;
+/**
+ * Creates a permissive instance ceiling (for general SaaS).
+ */
+export declare function createPermissiveInstanceCeiling(instanceId: string): TracelessInstanceCeiling;
+/**
+ * Clears all client-side storage (for traceless mode enforcement).
+ * WARNING: This clears ALL storage, not just app data.
+ */
+export declare function clearAllClientStorage(): void;
+/**
+ * Audit scanner: checks if any storage is being used against policy.
+ * Returns violations found.
+ */
+export declare function auditStorageCompliance(policy: ITracelessPolicy): StorageAuditResult;
+/**
+ * Storage audit result.
+ */
+export interface StorageAuditResult {
+    compliant: boolean;
+    violations: StorageViolation[];
+    auditedAt: number;
+    policy: TracelessMode;
+}
+/**
+ * Storage violation entry.
+ */
+export interface StorageViolation {
+    type: 'cookie' | 'localStorage' | 'sessionStorage';
+    severity: 'low' | 'medium' | 'high';
+    message: string;
+    data?: string;
+}
+declare const _default: {
+    DEFAULT_TRACELESS_POLICY: ITracelessPolicy;
+    TRACELESS_MODE_PRESETS: Record<TracelessMode, Omit<ITracelessPolicy, "source" | "version" | "resolvedAt">>;
+    PRIVACY_LEVEL_ORDER: TracelessMode[];
+    TRACELESS_POLICY_HEADER: string;
+    getMorePrivateMode: typeof getMorePrivateMode;
+    isAtLeastAsPrivate: typeof isAtLeastAsPrivate;
+    resolveTracelessPolicy: typeof resolveTracelessPolicy;
+    deriveMode: typeof deriveMode;
+    shouldShowConsentBanner: typeof shouldShowConsentBanner;
+    StorageAdapter: typeof StorageAdapter;
+    resolveControlStoragePermissions: typeof resolveControlStoragePermissions;
+    generateTracelessComplianceReport: typeof generateTracelessComplianceReport;
+    getTracelessBadgeInfo: typeof getTracelessBadgeInfo;
+    getGracefulDegradationInfo: typeof getGracefulDegradationInfo;
+    parsePolicyFromHeader: typeof parsePolicyFromHeader;
+    createPolicyHeader: typeof createPolicyHeader;
+    createStorageAdapter: typeof createStorageAdapter;
+    createRestrictiveInstanceCeiling: typeof createRestrictiveInstanceCeiling;
+    createPermissiveInstanceCeiling: typeof createPermissiveInstanceCeiling;
+    clearAllClientStorage: typeof clearAllClientStorage;
+    auditStorageCompliance: typeof auditStorageCompliance;
+};
+export default _default;
+//# sourceMappingURL=traceless.d.ts.map

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

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

package/dist/core/types.d.ts

@@ -0,0 +1,105 @@
+/** T-shirt sizing used across all components for consistent visual density. */
+export type NiceSize = 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/** @deprecated Legacy size names — use NiceSize values instead. */
+export type NiceSizeLegacy = 'small' | 'medium' | 'large';
+/**
+ * Normalizes a size value, converting deprecated legacy names to NiceSize.
+ * Emits a one-time console warning per legacy value in development mode.
+ */
+export declare function normalizeSize(size: string | undefined, componentName?: string): NiceSize;
+/**
+ * Layout sizing for editors, viewers and players.
+ * - `'minimal'` — smallest usable chrome, toolbar hidden or icon-only
+ * - `'compact'` — reduced padding, single-row toolbar
+ * - `'standard'` — default layout with full toolbar
+ * - `'fullscreen'` — expands to fill the viewport
+ */
+export type NiceEditorSize = 'minimal' | 'compact' | 'standard' | 'fullscreen';
+/** Visual style variant for buttons, alerts, badges and other themed controls. */
+export type NiceVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info' | 'ghost' | 'outline';
+/** Whitespace / padding density preset. */
+export type NiceDensity = 'compact' | 'normal' | 'comfortable';
+/**
+ * Per-component visibility & interaction level used by the access control system.
+ * - `'full'` — fully interactive (default)
+ * - `'readOnly'` — renders but cannot be edited
+ * - `'disabled'` — renders greyed-out
+ * - `'hidden'` — not rendered at all
+ */
+export type NiceAccessMode = 'full' | 'readOnly' | 'disabled' | 'hidden';
+/** Base props inherited by every NiceToDev component. */
+export interface NiceBaseProps {
+    /** Additional CSS class name(s). */
+    className?: string;
+    /** Inline style object. */
+    style?: React.CSSProperties;
+    /** HTML `id` attribute. When omitted a stable auto-generated id is used. */
+    id?: string;
+    /** Tooltip text shown on hover. */
+    title?: string;
+    /** Test identifier for integration / e2e test selectors. */
+    'data-testid'?: string;
+    /** Controls component visibility and interaction — see {@link NiceAccessMode}. */
+    accessMode?: NiceAccessMode;
+    /**
+     * Visual presentation style override.
+     * When set, overrides the global `displayStyle` from `NiceThemeProvider`.
+     * @see NiceDisplayStyle
+     */
+    displayStyle?: import('../core/displayStyle').NiceDisplayStyle;
+}
+/** Extended base props for form-field components (inputs, selects, etc.). */
+export interface NiceFormFieldProps extends NiceBaseProps {
+    /** Field label displayed above or beside the control. */
+    label?: string;
+    /** Assistive text shown below the field. */
+    helperText?: string;
+    /** Validation error message — when set the field is styled as invalid. */
+    error?: string;
+    /** Marks the field as required (adds visual indicator). */
+    required?: boolean;
+    /** Disables the field. */
+    disabled?: boolean;
+    /** Makes the field read-only. */
+    readOnly?: boolean;
+    /** Visual size of the field. */
+    size?: NiceSize;
+    /** HTML `name` attribute used in form serialization. */
+    name?: string;
+    /** When true, pressing Enter will trigger the onSubmit callback (if provided). */
+    submitOnEnter?: boolean;
+    /** Callback triggered when Enter is pressed (if submitOnEnter is true). */
+    onSubmit?: () => void;
+    /** Show a keyboard shortcuts hint icon (?) next to the label. */
+    showKeyboardHints?: boolean;
+    /** Label position: 'top' (default, stacked) or 'left' (inline beside the control). */
+    labelPlacement?: 'top' | 'left';
+    /** Error/validation position: 'bottom' (default) or 'right' (inline beside the control). */
+    errorPlacement?: 'bottom' | 'right';
+    /** Shows a loading spinner inside the control and disables interaction. */
+    loading?: boolean;
+    /** Explicit width for the label (e.g. '120px', '30%'). Only applies when labelPlacement is 'left'. */
+    labelWidth?: string | number;
+    /** Explicit width for the control (e.g. '200px', '50%'). Defaults to 100% in column layout. */
+    controlWidth?: string | number;
+    /** When `true`, the control renders as a clickable label-style display of the current value
+     * (no input border/chrome). Click switches it into the regular editable control. Useful for
+     * inline-editable cells or "click-to-edit" patterns — replaces the standalone NiceInPlaceEditor. */
+    displayMode?: boolean;
+}
+/** A single option displayed in selects, radio-groups, autocompletes and similar list-based editors. */
+export type NiceOption<T = string> = {
+    /** The option's backing value. */
+    value: T;
+    /** Display text shown to the user. */
+    label: string;
+    /** When `true` the option cannot be selected. */
+    disabled?: boolean;
+    /** Optional icon rendered before the label. */
+    icon?: React.ReactNode;
+    /** Secondary description text. */
+    description?: string;
+    /** Grouping key for grouped dropdowns. */
+    group?: string;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/core/useThemeIsDark.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Live boolean indicating whether the active theme renders as "dark".
+ *
+ * Resolution order:
+ * 1. `<html data-theme="dark|light">` attribute (explicit consumer wins)
+ * 2. `nice-dark` / `nice-light` (and bare `dark`) class on `<html>`
+ * 3. `--text-primary` CSS variable luminance (light text → dark theme)
+ * 4. `prefers-color-scheme: dark` media query as last-resort fallback
+ *
+ * Updates whenever any of the above change (MutationObserver on `<html>`
+ * attributes/class/style + media-query listener), so canvas-based renderers
+ * (QR, barcode, charts…) stay in sync without consumers wiring `useDarkMode`.
+ */
+export declare function useThemeIsDark(): boolean;
+//# sourceMappingURL=useThemeIsDark.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useThemeIsDark.d.ts","sourceRoot":"","sources":["../../src/core/useThemeIsDark.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,IAAI,OAAO,CA4BxC"}