npm - @privacykit/web - Versions diffs - 0.1.0 → 0.1.2 - Mend

@privacykit/web 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@privacykit/web",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Developer-friendly GDPR consent management with real enforcement.",
   "main": "index.js",
   "keywords": [
@@ -14,5 +14,17 @@
   "license": "MIT",
   "devDependencies": {
     "typescript": "^6.0.3"
+  },
+  "files": [
+    "dist",
+    "privacykit.d.ts",
+    "styles.css",
+    "readme.md"
+  ],
+  "scripts": {
+    "sync-types": "cp ../privacykit-sdk/public/privacykit.d.ts ./privacykit.d.ts",
+    "update:patch": "npm run sync-types && npm version patch",
+    "update:minor": "npm run sync-types && npm version minor",
+    "publish": "npm publish"
   }
 }

package/privacykit.d.ts ADDED Viewed

@@ -0,0 +1,373 @@
+export {};
+declare global {
+  /**
+   * PrivacyKit web component type declarations.
+   *
+   * Drop this file into any TypeScript project and add it to the
+   * "include" array in tsconfig.json, or place it in a `types/` folder
+   * that TypeScript already scans.
+   *
+   * Supported components:
+   *   <consent-dialog>   — cookie consent banner / modal
+   *   <consent-guard>    — conditionally renders content based on consent
+   *   <consent-missing>  — fallback shown when consent is absent
+   *
+   * CDN usage:
+   * PrivacyKit web components are distributed as static assets through a CDN.
+   * Add this to your <head> (module builds):
+   * <script type="module" src="https://cdn.privacykit.eu/v1/privacykit.esm.js"></script>
+   *
+   * Framework notes:
+   *   - React: JSX typings are included below (React 18 global + scoped JSX).
+   *   - Vue 3: no extra typings required; configure `compilerOptions.isCustomElement`
+   *            for `consent-dialog`, `consent-guard`, and `consent-missing`.
+   *   - Angular: no extra typings required; add `CUSTOM_ELEMENTS_SCHEMA` where
+   *              these elements are used.
+   *   - Svelte: no extra typings required for runtime usage.
+   */
+  // ── Shared types ──────────────────────────────────────────────────────────────
+  /** Visual variant of the consent dialog. */
+  type ConsentDialogVariant = 'standard' | 'modern' | 'modest' | 'panel';
+  /** Token preset theme of the consent dialog. */
+  type ConsentDialogTheme = 'standard' | 'dark' | 'teal' | 'slate' | 'light' | 'vibrant' | 'high-contrast';
+  /** Locale supported by PrivacyKit. Falls back to 'en'. */
+  type ConsentDialogLocale = 'da' | 'de' | 'en' | 'es' | 'fi' | 'fr' | 'it' | 'nl' | 'no' | 'pl' | 'sv';
+  /**
+   * Payload dispatched on `window` as the `privacykit:consent-changed` event.
+   *
+   * @example
+   * window.addEventListener('privacykit:consent-changed', (e) => {
+   *   const { consent, mode } = (e as CustomEvent<PrivacyKitConsentChangedDetail>).detail;
+   * });
+   */
+  interface PrivacyKitConsentChangedDetail {
+    consent: {
+      analytics: boolean;
+      marketing: boolean;
+      preferences: boolean;
+    };
+    mode: 'accept-all' | 'accept-selected' | 'reject-all';
+    timestamp: string;
+  }
+  interface PrivacyKitConsentState {
+    analytics: boolean;
+    marketing: boolean;
+    preferences: boolean;
+  }
+  interface PrivacyKitSubscriptionStatus {
+    status: string | null;
+    billingInterval: string | null;
+    subscriptionEnd: string | null;
+    trailingEnd: string | null;
+  }
+  interface PrivacyKitGlobalApi {
+    readConsent(): PrivacyKitConsentState | null;
+    hasConsent(expression?: string): boolean;
+    onConsentChanged(callback: (consent: PrivacyKitConsentState | null) => void): () => void;
+    openConsentDialog(): void;
+    openPrivacyPolicyDialog(): void;
+    onConsentDialogClosed(callback: () => void): () => void;
+    getSubscriptionStatus(): PrivacyKitSubscriptionStatus | null;
+    /**
+     * Toggle the compliance monitor UI by flipping the `debug` prop on the <compliance-monitor> element.
+     * No parameters; flips the current debug state.
+     */
+    toggleComplianceMonitor(): void;
+    /**
+     * Subscribes to the privacykit:ready event. Callback is called when PrivacyKit is ready.
+     * Replay-safe: if PrivacyKit is already ready when you subscribe, the callback still runs once.
+     * Returns an unsubscribe function.
+     */
+    onReady(callback: () => void): () => void;
+    subscriptionStatus?: PrivacyKitSubscriptionStatus | null;
+  }
+  // ── DOM element interfaces ────────────────────────────────────────────────────
+  /**
+   * `<consent-dialog>` — the public entry component.
+   *
+   * Manages open/close state, locale resolution, and variant routing.
+   * All visual rendering is delegated to the active design variant.
+   *
+   * Named slots for content overrides:
+   *   - `dialog-logo`         Optional logo content shown next to the title
+   *   - `dialog-logo-alt`     Alternative location for your brand logo
+   *   - `dialog-title`        Override the dialog heading
+   *   - `dialog-summary-part-1` Override the first summary paragraph
+   *   - `dialog-summary-part-2` Override the second summary paragraph
+   *   - `necessary-content`   Override "Functional cookies" body text
+   *   - `preferences-content` Override "Preferences" body text
+   *   - `analytics-content`   Override "Analytics" body text
+   *   - `marketing-content`   Override "Marketing" body text
+   *   - `read-more-title`     Override the "Read more" label
+   *   - `read-more-content`   Override the read-more body text
+   *   - `privacy-policy-content` Override the privacy policy content
+   *
+   * CSS custom properties:
+   *   --pk-bg-color        Dialog background color
+   *   --pk-text-color      Dialog text color
+   *   --pk-primary-color   Accent / primary color
+   *   --pk-border-width    Border width
+   *   --pk-radius          Border radius
+   *   --pk-dialog-max-height Dialog max height
+   *   --pk-font-family     Font family
+   *   --pk-spacing-unit    Base spacing unit (rem)
+   */
+  interface HTMLConsentDialogElement extends HTMLElement {
+    /** Visual variant for consent UI. @default 'standard' */
+    variant: ConsentDialogVariant;
+    /** Token preset theme for dialog design tokens. @default 'standard' */
+    theme: ConsentDialogTheme;
+    /** Cookie TTL in days. @default 180 */
+    expiresDays: number;
+    /** Schema version string; triggers re-consent when changed. @default 0 */
+    version: number;
+    /** Explicit locale override. Auto-detected from browser when omitted. */
+    locale: string | undefined;
+    /** Hide the "Strictly necessary" section from the dialog. */
+    hideNecessary: boolean | undefined;
+    /** Hide the "Preferences" section from the dialog. */
+    hidePreferences: boolean | undefined;
+    /** Hide the "Analytics" section from the dialog. */
+    hideAnalytics: boolean | undefined;
+    /** Hide the "Marketing" section from the dialog. */
+    hideMarketing: boolean | undefined;
+    /** Hide the expandable "Read more" section from the dialog. */
+    hideReadmore: boolean | undefined;
+    /** Hide the default Privacy Policy link in the footer. */
+    hidePrivacyPolicyLink: boolean | undefined;
+    /** Override the privacy policy link to redirect to an external URL instead of opening the internal privacy policy dialog. */
+    privacyPolicyUrl: string | undefined;
+    /** Hide the second summary paragraph from the dialog. */
+    hideSummaryPart2: boolean | undefined;
+    /** Demo mode: disables auto-open and mocks subscription status. */
+    demo: boolean | undefined;
+    /** Show a floating action button to re-open the dialog. Only visible once a consent cookie exists. @default false */
+    showFab: boolean;
+    /** Position of the FAB in the viewport. @default 'left' */
+    fabPosition: 'left' | 'right';
+    /** Whether the dialog is currently open. @default false */
+    open: boolean;
+    /** Programmatically open the dialog. */
+    openDialog(): Promise<void>;
+    /** Programmatically close the dialog. */
+    closeDialog(): Promise<void>;
+    /** Re-fetch the subscription status from the API. */
+    checkSubscriptionStatus(): Promise<void>;
+  }
+  /**
+   * `<consent-guard>` — renders slot content only when the required consent is granted.
+   *
+   * Activates `<script type="text/plain">` children by cloning them as live scripts.
+   * Listens to the `privacykit:consent-changed` window event for reactive updates.
+   *
+   * @example Single category
+   * <consent-guard consent="analytics">...</consent-guard>
+   *
+   * @example AND — require all listed (space-separated with `+`)
+   * <consent-guard consent="analytics+marketing">...</consent-guard>
+   *
+   * @example OR — require any one (pipe-separated)
+   * <consent-guard consent="analytics|marketing">...</consent-guard>
+   *
+   * @example Default — omit `consent` to require ALL categories
+   * <consent-guard>...</consent-guard>
+   */
+  interface HTMLConsentGuardElement extends HTMLElement {
+    /**
+     * Consent expression to evaluate. Omit to require ALL categories.
+     *
+     * Single:    `"analytics"` | `"marketing"` | `"preferences"`
+     * AND (all): `"analytics+marketing"` | `"analytics+marketing+preferences"`
+     * OR  (any): `"analytics|marketing"` | `"analytics|preferences"`
+     */
+    consent: string | undefined;
+  }
+  /**
+   * `<consent-missing>` — shows fallback content when a paired `<consent-guard>` is blocked.
+   *
+   * Observes attribute changes on the target guard element and displays its
+   * slot content whenever `data-pk-blocked` is present on the guard.
+   *
+   * @example
+   * <consent-guard consent="analytics" id="analytics-guard">...</consent-guard>
+   * <consent-missing for="analytics-guard">Please accept analytics to continue.</consent-missing>
+   */
+  interface HTMLConsentMissingElement extends HTMLElement {
+    /** The `id` of the paired `<consent-guard>` element. */
+    for: string;
+  }
+  /**
+   * `<compliance-monitor>` — developer compliance monitor for outgoing requests.
+   *
+   * Shows a floating action button (FAB) and dialog UI for monitoring outgoing
+   * network requests and their consent/guard status. Intended for developer/debug use.
+   *
+   * Props:
+   *   - `debug` (boolean): Show FAB and enable monitor UI (default: false)
+   *   - `delay` (number): Observation window in ms (default: 5000)
+   *   - `compliance-state` (string): Current compliance state (readonly, for status)
+   *
+   * Usage:
+   *   <compliance-monitor debug delay="5000"></compliance-monitor>
+   */
+  interface HTMLComplianceMonitorElement extends HTMLElement {
+    /** Show FAB and enable monitor UI. */
+    debug: boolean;
+    /** Observation window in ms. */
+    delay: number;
+    /** Exclude requests to first-party subdomains from compliance checks. @default true */
+    ignoreFirstPartySubdomains: boolean;
+    /** Position of the FAB in the viewport (vertically centered). @default 'right' */
+    fabPosition: 'left' | 'right';
+    /** Current compliance state (readonly). */
+    complianceState: 'observing' | 'observation_complete_success' | 'observation_complete_warning';
+  }
+  interface Window {
+    PrivacyKit?: PrivacyKitGlobalApi;
+  }
+  interface HTMLElementTagNameMap {
+    'consent-dialog': HTMLConsentDialogElement;
+    'consent-guard': HTMLConsentGuardElement;
+    'consent-missing': HTMLConsentMissingElement;
+    'compliance-monitor': HTMLComplianceMonitorElement;
+  }
+  interface WindowEventMap {
+    'privacykit:consent-changed': CustomEvent<PrivacyKitConsentChangedDetail>;
+  }
+}
+// ── React JSX augmentation ────────────────────────────────────────────────────
+//
+// React passes custom element props as DOM attributes. Boolean Stencil props
+// (e.g. `noNecessary`) map to their kebab-case HTML attribute names (e.g.
+// `no-necessary`). Presence without a value or `={true}` both set the attribute.
+//
+// Ref: React 19 (used by Next.js 15+) has full custom-element support — props
+// that are not event handlers are passed as attributes automatically.
+type CKRef<T> = { current: T | null } | ((instance: T | null) => void) | null;
+interface ConsentDialogJSXProps {
+  /** Visual variant. @default 'standard' */
+  'variant'?: ConsentDialogVariant;
+  /** Token preset theme. @default 'standard' */
+  'theme'?: ConsentDialogTheme;
+  /** Cookie TTL in days. @default 180 */
+  'expires-days'?: number;
+  /** Policy version; bump to force re-consent. @default 0 */
+  'version'?: number;
+  /** Locale override. Defaults to browser locale. */
+  'locale'?: string;
+  /** Hide the "Strictly necessary" section. */
+  'hide-necessary'?: boolean | '';
+  /** Hide the "Preferences" section. */
+  'hide-preferences'?: boolean | '';
+  /** Hide the "Analytics" section. */
+  'hide-analytics'?: boolean | '';
+  /** Hide the "Marketing" section. */
+  'hide-marketing'?: boolean | '';
+  /** Hide the second summary paragraph. */
+  'hide-summary-part-2'?: boolean | '';
+  /** Enable demo mode. */
+  'demo'?: boolean | '';
+  /** Show a floating action button to re-open the dialog once consent has been given. @default false */
+  'show-fab'?: boolean | '';
+  /** Position of the FAB: bottom-left or bottom-right. @default 'left' */
+  'fab-position'?: 'left' | 'right';
+  /** Open/close state. */
+  'open'?: boolean | '';
+  'ref'?: CKRef<HTMLConsentDialogElement>;
+  'children'?: unknown;
+  /** Inline styles — pass CSS custom properties like `--pk-primary-color` here. */
+  'style'?: Record<string, string | number>;
+  'class'?: string;
+  'className'?: string;
+  'id'?: string;
+}
+interface ConsentGuardJSXProps {
+  /**
+   * Consent expression. Omit to require ALL categories.
+   *
+   * Single:    `"analytics"` | `"marketing"` | `"preferences"`
+   * AND (all): `"analytics+marketing"` | `"analytics+marketing+preferences"`
+   * OR  (any): `"analytics|marketing"` | `"analytics|preferences"`
+   */
+  consent?: string;
+  ref?: CKRef<HTMLConsentGuardElement>;
+  children?: unknown;
+  style?: Record<string, string | number>;
+  class?: string;
+  className?: string;
+  id?: string;
+}
+interface ConsentMissingJSXProps {
+  /** ID of the paired `<consent-guard>` element. */
+  for: string;
+  ref?: CKRef<HTMLConsentMissingElement>;
+  children?: unknown;
+  style?: Record<string, string | number>;
+  class?: string;
+  className?: string;
+  id?: string;
+}
+interface ComplianceMonitorJSXProps {
+  /** Show FAB and enable monitor UI. */
+  'debug'?: boolean | '';
+  /** Observation window in ms. */
+  'delay'?: number;
+  /** Exclude requests to first-party subdomains from compliance checks. @default true */
+  'ignore-first-party-subdomains'?: boolean | '';
+  /** Position of the FAB in the viewport (vertically centered). @default 'right' */
+  'fab-position'?: 'left' | 'right';
+  /** Current compliance state (readonly). */
+  'compliance-state'?: 'observing' | 'observation_complete_success' | 'observation_complete_warning';
+  'ref'?: CKRef<HTMLComplianceMonitorElement>;
+  'style'?: Record<string, string | number>;
+  'class'?: string;
+  'className'?: string;
+  'id'?: string;
+}
+// React 18 global JSX namespace (also consumed by older Next.js setups)
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare namespace JSX {
+  interface IntrinsicElements {
+    'consent-dialog': ConsentDialogJSXProps;
+    'consent-guard': ConsentGuardJSXProps;
+    'consent-missing': ConsentMissingJSXProps;
+    'compliance-monitor': ComplianceMonitorJSXProps;
+  }
+}
+// React 18+ scoped JSX namespace (preferred in modern Next.js / React setups)
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'consent-dialog': ConsentDialogJSXProps;
+      'consent-guard': ConsentGuardJSXProps;
+      'consent-missing': ConsentMissingJSXProps;
+      'compliance-monitor': ComplianceMonitorJSXProps;
+    }
+  }
+}

package/styles.css ADDED Viewed

@@ -0,0 +1,11 @@
+consent-dialog:not(:defined) [slot] {
+  display: none;
+}
+consent-guard:not([active]) {
+  display: none;
+}
+consent-missing:not([active]) {
+  display: none;
+}

package/src/index.ts DELETED Viewed

	@@ -1 +0,0 @@
1	- export const PRIVACYKIT_PACKAGE_VERSION = "0.1.0";