@soyio/soyio-widget 2.17.0 → 2.19.0

package/README.md

@@ -24,6 +24,7 @@
 - [Auth Request](#auth-request)
 - [Appearance](#appearance)
 - [TypeScript](#typescript)
+- [JSON Schema Validation](#json-schema-validation)
 - [Server Side Rendering (SSR)](#server-side-rendering-ssr)
 
 
@@ -164,6 +165,10 @@ The `PrivacyCenterBox` lets you embed the Privacy Center inside your page. You c
     // Feature flags (optional)
     enabledFeatures: ["DataSubjectRequest", "ConsentManagement"],
 
+    // DSR rights to show (optional)
+    // When omitted, the DSR form will use arsop right as default
+    enabledRights: ["arsop"],
+
     // Request reference (optional)
     // Will be attached to data subject requests
     requestReference: "<reference>", // e.g. some uuid or id to match our created records with your frontend flows
@@ -197,6 +202,7 @@ The `PrivacyCenterBox` lets you embed the Privacy Center inside your page. You c
 - `sessionToken`: Use this to authenticate a session directly.
 - `companyId`: The company identifier. Must start with `com_`. Use this when Privacy Center is mounted in a non authenticated environment.
 - `enabledFeatures`: Optional array of features to show. Supported values: `"DataSubjectRequest"`, `"ConsentManagement"`.
+- `enabledRights`: Optional array of rights for the Data Subject Request (DSR) form. Supported values: `"arsop"`, `"redec"`. When multiple values are provided, the form starts with a right selection step. When a single value is provided, the selection step is skipped. When omitted, the form defaults to arsop rights.
 - `requestReference`: Optional string, intended to be a reference of the current session. It will be attached to created data subject requests.
 - `dataSubjects`: Optional array of data subject categories. When present, the consent management view only shows consent for the specified categories. Supported values include: `"anonymous_user"`, `"citizen_voter"`, `"commuter"`, `"consultant"`, `"customer"`, `"employee"`, `"job_applicant"`, `"next_of_kin"`, `"passenger"`, `"patient"`, `"prospect"`, `"shareholder"`, `"supplier_vendor"`, `"trainee"`, `"visitor"`.
 - `fileRequisites`: Optional object to configure file upload constraints.
@@ -518,6 +524,7 @@ interface Config {
   };
   iconRules?: Record<string, { weight?: IconWeight; size?: number }>;
   mainPageColumns?: 1 | 2 | 3 | 4;
+  brandTheme?: 'default' | 'dark' | 'light';
 }
 ```
 
@@ -529,6 +536,7 @@ interface Config {
 | `icon.size` | Global default icon size in pixels | `24` |
 | `iconRules` | Per-component icon style overrides | `{}` |
 | `mainPageColumns` | Number of columns in the main page feature cards grid (1-4) | `2` |
+| `brandTheme` | Theme variant for branded elements like the footer (`default`, `dark`, `light`) | `"default"` |
 
 #### Icons
 
@@ -823,6 +831,15 @@ The step indicator shows progress through multi-step forms.
 - `.Chip--red` - Red chip variant.
 - `.Chip--amber` - Amber chip variant.
 
+##### Consent Components
+
+The following rules are specific to the **Consent Box** widget and allow customization of consent-related UI elements:
+
+- `.CategoryTag` - Data use category identifier (e.g., "Compartir datos con terceros"). Appears above category descriptions in expanded consent views.
+- `.Badge` - Optional/required label badge appearing on consent items.
+
+> **Note:** These consent-specific rules are only available in the `ConsentBox` widget and will have no effect in other widgets like `PrivacyCenterBox`.
+
 ### Example Configuration
 
 ```javascript
@@ -904,6 +921,79 @@ To use the `SoyioTypes` in your project, import it directly from the `@soyio/soy
 import type { SoyioTypes } from "@soyio/soyio-widget";
 ```
 
+## JSON Schema Validation
+
+The package includes JSON Schemas for validating configuration objects. This is useful for:
+- **IDE Autocomplete**: Get IntelliSense in your editor when writing configurations
+- **Runtime Validation**: Validate user-provided configurations before passing to the widget
+- **Documentation**: Use schemas to generate API documentation
+
+### Available Schemas
+
+#### Appearance Schema
+Validates appearance customization objects (theme, variables, rules, config):
+
+```javascript
+// Import the schema
+import appearanceSchema from "@soyio/soyio-widget/schemas/appearance";
+
+// Use with a validator like Ajv
+import Ajv from "ajv";
+const ajv = new Ajv();
+const validate = ajv.compile(appearanceSchema);
+
+const appearance = {
+  theme: "night",
+  variables: {
+    colorPrimary: "#007bff",
+    borderRadius: "8px"
+  }
+};
+
+if (validate(appearance)) {
+  console.log("✅ Valid appearance config");
+} else {
+  console.error("❌ Invalid:", validate.errors);
+}
+```
+
+#### Config Schema
+Validates complete widget configuration including Privacy Center and Consent Box options:
+
+```javascript
+import configSchema from "@soyio/soyio-widget/schemas/config";
+
+const validate = ajv.compile(configSchema);
+const config = {
+  companyId: "com_example",
+  appearance: { /* ... */ },
+  onEvent: (event) => console.log(event)
+};
+
+if (validate(config)) {
+  const privacyCenter = new PrivacyCenterBox(config);
+  privacyCenter.mount("#container");
+}
+```
+
+### Using Schemas with Monaco Editor
+
+Perfect for building configuration editors:
+
+```javascript
+import * as monaco from "monaco-editor";
+import configSchema from "@soyio/soyio-widget/schemas/config";
+
+monaco.languages.json.jsonDefaults.setDiagnosticsOptions({
+  validate: true,
+  schemas: [{
+    uri: "https://soyio.id/widget-config.json",
+    fileMatch: ["*"],
+    schema: configSchema
+  }]
+});
+```
+
 ## Server Side Rendering (SSR)
 
 This package is not directly compatible with SSR because of `post-robot`, but there are workarounds that allow you to use it without disrupting the build process. Below are examples on popular SSR frameworks.

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+import { default as appearanceSchema } from './schemas/appearance.schema.json';
+import { default as configSchema } from './schemas/config.schema.json';
+
+export { appearanceSchema }
+
 declare type AuthRequestConfig = {
     request: 'authentication_request';
     configProps: AuthRequestProps;
@@ -21,12 +26,14 @@ declare type BaseConfig = {
 
 declare abstract class BaseIframeBox<T extends BaseConfig> {
     protected iframe: HTMLIFrameElement | null;
+    protected wrapper: HTMLDivElement | null;
     protected skeleton: ISkeletonView | null;
     protected readonly options: T;
-    protected readonly appearance: SoyioAppearance | null;
+    protected appearance: SoyioAppearance | null;
     protected readonly tooltipManager: _TooltipManager;
     readonly defaultIframeCSSConfig: IframeCSSConfig;
     protected Skeleton: SkeletonConstructor | null;
+    private isIframeReady;
     private readonly defaultUniqueId;
     abstract readonly defaultIframePrefix: string;
     constructor(options: T);
@@ -40,10 +47,17 @@ declare abstract class BaseIframeBox<T extends BaseConfig> {
     protected setupListeners(): Promise<void>;
     mount(selector: string): Promise<this>;
     unmount(): void;
+    /**
+     * Update the appearance of the widget without remounting.
+     * This sends the new appearance config to the already-mounted iframe.
+     */
+    updateAppearance(appearance: SoyioAppearance): Promise<void>;
 }
 
 declare const CLOSED_EVENT = "WIDGET_CLOSED";
 
+export { configSchema }
+
 export declare class ConsentBox extends BaseIframeBox<ConsentConfig> {
     readonly defaultIframePrefix = "consent-box";
     readonly defaultIframeCSSConfig: IframeCSSConfig;
@@ -241,8 +255,10 @@ export declare class PrivacyCenterBox extends BaseIframeBox<PrivacyCenterConfig>
 
 declare type PrivacyCenterConfig = BaseConfig & {
     enabledFeatures?: PrivacyManagerFeature[];
+    enabledRights?: PrivacyCenterRight[];
     dataSubjects?: DataSubject[];
     requestReference?: string;
+    demo?: boolean;
     fileRequisites?: {
         allowedExtensions?: string[];
         maxFileSize?: number;
@@ -255,6 +271,8 @@ declare type PrivacyCenterConfig = BaseConfig & {
     companyId?: never;
 });
 
+declare type PrivacyCenterRight = 'arsop' | 'redec';
+
 declare type PrivacyManagerFeature = 'DataSubjectRequest' | 'ConsentManagement' | 'RequestTracking';
 
 declare type Request_2 = 'disclosure' | 'signature' | 'authentication';
@@ -274,7 +292,7 @@ declare type SignatureRequestConfig = {
     developmentUrl?: string;
 };
 
-declare type SkeletonConstructor = new (id: string) => ISkeletonView;
+declare type SkeletonConstructor = new (id: string, theme?: SoyioTheme) => ISkeletonView;
 
 declare interface SoyioAppearance {
     theme?: SoyioTheme;
@@ -315,6 +333,14 @@ declare interface SoyioAppearanceConfig {
      * @default 2
      */
     mainPageColumns?: 1 | 2 | 3 | 4;
+    /**
+     * Theme variant for branded elements like the footer.
+     * - 'default': Standard Soyio brand colors (purple/indigo)
+     * - 'dark': Dark mode with gray tones
+     * - 'light': Mono color light version
+     * @default 'default'
+     */
+    brandTheme?: 'default' | 'dark' | 'light';
 }
 
 declare interface SoyioAppearanceVariables {
@@ -353,6 +379,7 @@ declare interface SoyioAppearanceVariables {
     colorDanger?: string;
     colorDangerBg?: string;
     colorOverlay?: string;
+    dataUseIconColor?: string;
 }
 
 declare type SoyioBaseRule = '.MainContainer' | '.Button' | '.Checkbox' | '.CheckboxInput' | '.CheckboxLabel' | '.Input' | '.Label' | '.HintIcon' | '.Title' | '.StepTitle' | '.Link' | '.Card' | '.CardTitle' | '.Select' | '.Loader' | '.TextArea' | '.ErrorMessage' | '.Description' | '.Switch' | '.SwitchRoot' | '.SwitchThumb' | '.SwitchIcon' | '.Alert' | '.AlertIcon' | '.AlertContent' | '.Radio' | '.RadioButton' | '.RadioIndicator' | '.RadioLabel' | '.Chip' | '.Dialog' | '.DialogOverlay' | '.DialogContent' | '.DialogTitle' | '.DialogDescription' | '.Combobox' | '.NinInput' | '.TrackingCodeInput' | '.TrackingCodeInputCell' | '.TrackingCodeInputSeparator' | '.RadioCard' | '.RadioCardButton' | '.RadioCardIndicator' | '.RadioCardTitle' | '.StepIndicatorContainer' | '.StepIndicator' | '.StepIndicatorLine' | '.StepIndicatorIcon' | '.StepIndicatorDot' | '.StepIndicatorNumber' | '.TooltipContent';
@@ -376,6 +403,11 @@ declare interface SoyioIconConfig {
      * @default 24
      */
     size?: number;
+    /**
+     * Override variant for data use icons in consent management.
+     * If not set, uses the company's configured iconVariant.
+     */
+    dataUseVariant?: 'duotone' | 'outline' | 'solid';
 }
 
 declare type SoyioPseudoClass = ':hover' | ':focus' | ':active' | ':disabled' | ':autofill' | ':focus-visible';