### Example: Audience Setup Wizard Component

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

An example demonstrating the usage of various Newspack and WordPress components within a wizard screen, including `Notice`, `Card`, `ActionCard`, `Grid`, `RangeControl`, and `Button`.

```jsx
import { CheckboxControl, ExternalLink, RangeControl } from '@wordpress/components';
import {
	ActionCard,
	Button,
	Card,
	Grid,
	Notice,
	Divider,
	PluginInstaller,
	SectionHeader,
	TextControl,
	Waiting,
	withWizardScreen,
} from '../../../../../packages/components/src';

export default withWizardScreen( ( { config, updateConfig } ) => {
	return (
		<>
			<Notice noticeText={ __( 'Audience Management is enabled.', 'newspack-plugin' ) } isSuccess />
			<Card noBorder>
				<ActionCard
					title={ __( 'Present newsletter signup after checkout', 'newspack-plugin' ) }
					toggleChecked={ config.use_custom_lists }
					toggleOnChange={ value => updateConfig( 'use_custom_lists', value ) }
				>
					<Grid columns={ 4 }>
						<RangeControl
							label={ __( 'Initial list size', 'newspack-plugin' ) }
							value={ config.newsletter_list_initial_size }
							onChange={ value => updateConfig( 'newsletter_list_initial_size', parseInt( value ) ) }
						/>
					</Grid>
				</ActionCard>
			</Card>
			<div className="newspack-buttons-card">
				<Button variant="primary" onClick={ saveConfig }>
					{ __( 'Save Settings', 'newspack-plugin' ) }
				</Button>
			</div>
		</>
	);
} );
```

--------------------------------

### Install a Plugin

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Install a plugin, which involves downloading and then activating it. This is useful for plugins that are not already present on the site.

```php
// Install (download + activate) a plugin
$result = 
Newspack\
Plugin_Manager::install( 'co-authors-plus' );
```

--------------------------------

### Get Integration Setup URL

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Provide the admin URL where the integration's prerequisites can be configured. Defaults to an empty string.

```php
public function get_setup_url()
```

--------------------------------

### Start Development Server

Source: https://github.com/automattic/newspack-plugin/blob/trunk/README.md

Run this command to compile SCSS and JS files and start a file watcher for development.

```bash
npm start
```

--------------------------------

### Install Newspack Icons

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/icons/README.md

Install the newspack-icons package using npm.

```bash
npm install newspack-icons
```

--------------------------------

### Install Newspack Colors

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/colors/README.md

Install the newspack-colors package using npm.

```bash
npm install newspack-colors
```

--------------------------------

### Overlay Menu Block Usage Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/src/blocks/overlay-menu/README.md

Example markup demonstrating how to use the Overlay Menu block, including its trigger and panel sub-blocks, within a block theme.

```html
<!-- wp:newspack/overlay-menu -->
<div class="wp-block-newspack-overlay-menu">
  <!-- wp:newspack/overlay-menu-trigger {"triggerText":"Menu"} /-->
  <!-- wp:newspack/overlay-menu-panel {"slideDirection":"left"} -->
  <div class="wp-block-newspack-overlay-menu-panel">
    <!-- wp:navigation {"overlayMenu":"never","layout":{"type":"flex","orientation":"vertical"}} /-->
  </div>
  <!-- /wp:newspack/overlay-menu-panel -->
</div>
<!-- /wp:newspack/overlay-menu -->
```

--------------------------------

### Minimum Integration Class Implementation

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Example of a minimal integration class extending \Newspack\Reader_Activation\Integration. Implement constructor, settings fields, and sync logic.

```php
namespace Newspack\My_Plugin;

use Newspack\Reader_Activation\Integration;

class My_Integration extends Integration {
    public function __construct() {
        parent::__construct(
            'my_integration',
            __( 'My Integration', 'my-plugin' ),
            __( 'Syncs reader data with My Service.', 'my-plugin' )
        );
    }

    public function register_settings_fields() {
        return [
            [
                'key'     => 'api_key',
                'type'    => 'password',
                'label'   => __( 'API Key', 'my-plugin' ),
                'default' => '',
            ],
        ];
    }

    public function can_sync( $return_errors = false ) {
        $errors = new \WP_Error();
        if ( ! $this->get_settings_field_value( 'api_key' ) ) {
            $errors->add( 'no_api_key', __( 'API key is missing.', 'my-plugin' ) );
        }
        if ( $return_errors ) {
            return $errors;
        }
        return ! $errors->has_errors();
    }

    public function push_contact_data( $contact, $context = '', $existing_contact = null ) {
        $contact = $this->prepare_contact( $contact );
        // ... push $contact to your API.
        return true;
    }
}
```

--------------------------------

### Stack Layout Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/src/newspack-ui/UTILITY_CLASSES.md

Demonstrates a vertical stack layout with a gap of 3 units and centered alignment.

```html
<div class="newspack-ui__stack newspack-ui__stack--vertical newspack-ui__stack--gap-3 newspack-ui__stack--align-center">
  <p>Item one</p>
  <p>Item two</p>
</div>
```

--------------------------------

### Imperative ConfirmDialog Usage

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/confirm-dialog/README.md

An example showing how to use the ConfirmDialog imperatively to guard both navigation and an action, using both `when` and `isOpen` props together.

```APIDOC
## Imperative ConfirmDialog Usage

### Description
An example showing how to use the ConfirmDialog imperatively to guard both navigation and an action, using both `when` and `isOpen` props together.

### Usage

```jsx
import { ConfirmDialog } from 'newspack-components';
import { useState } from 'react';

// Guard both navigation and an imperative action with a single dialog instance.
// isOpen triggers the dialog immediately (e.g. on a button click) without
// blocking navigation. Both when and isOpen can be used together.
const [ pendingAction, setPendingAction ] = useState( null );
<ConfirmDialog
	when={ hasUnsavedChanges }
	isOpen={ !! pendingAction }
	confirmButtonText="Discard changes"
	isDestructive
	hideTitle
	onConfirm={ () => {
		pendingAction?.();
		setPendingAction( null );
	} }
	onCancel={ () => setPendingAction( null ) }
>
	You have unsaved changes that will be lost. Discard changes?
</ConfirmDialog>
```
```

--------------------------------

### Visual Hierarchy: Wizard Step Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Shows the structure for a wizard step within a `withWizardScreen` layout, including optional notices, cards, action cards, and buttons.

```jsx
withWizardScreen
  Notice (optional)
  Card noBorder
    ActionCard (toggle + description)
      [Expandable content when enabled]
    Divider
    ActionCard
  .newspack-buttons-card
    Button
```

--------------------------------

### Example: Using Icons in UI Components

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/icons/DEVELOPMENT.md

Demonstrates the integration of icons within various UI components like boxes and buttons, using `print_svg()` to render the icons.

```php
<div class="newspack-ui__box newspack-ui__box--success">
	<span class="newspack-ui__icon newspack-ui__icon--success">
		<?php Newspack_UI_Icons::print_svg( 'check' ); ?>
	</span>
	<p>Success message with icon</p>
</div>

<button class="newspack-ui__button newspack-ui__button--primary">
	<?php Newspack_UI_Icons::print_svg( 'account' ); ?>
	Account Settings
</button>
```

--------------------------------

### Spacing Utility Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/src/newspack-ui/UTILITY_CLASSES.md

Applies no top margin and a 24px bottom margin to elements.

```html
<h4 class="newspack-ui__font--m newspack-ui__spacing-top--0">No top margin</h4>
<div class="newspack-ui__spacing-bottom--5">24px bottom margin</div>
```

--------------------------------

### Initialize Newspack Singleton Instance

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Call Newspack::instance() to bootstrap the plugin, initializing constants and hooks. Use Newspack::is_setup_complete() to check if setup is done, Newspack::is_debug_mode() for debug mode, Newspack::plugin_url() for the plugin's base URL, and Newspack::load_common_assets() to enqueue common assets.

```php
// newspack.php — called automatically on plugin load
Newspack::instance();

// Check if the initial setup wizard has been completed
if ( Newspack::is_setup_complete() ) {
    // Site is configured — safe to run revenue features
}

// Enable debug mode by defining WP_NEWSPACK_DEBUG in wp-config.php
// define( 'WP_NEWSPACK_DEBUG', true );
if ( Newspack::is_debug_mode() ) {
    // Extra logging is active; reset options via ?newspack_reset=reset
}

// Get the plugin's base URL (used to enqueue assets)
$plugin_url = Newspack::plugin_url();
// e.g. https://example.com/wp-content/plugins/newspack-plugin

// Enqueue shared JS/CSS commons bundle from any wizard or admin page
Newspack::load_common_assets();
// Registers and enqueues: dist/commons.js, dist/commons.css, dist/admin.css
```

--------------------------------

### Visual Hierarchy: Settings Screen Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Illustrates the typical structure and spacing for a settings screen using Newspack components like Wizard, SectionHeader, Card, ActionCard, Grid, and Button.

```jsx
Wizard
  GlobalNotices
  SectionHeader          ← 64px top margin
  Card                   ← 32px margin
    ActionCard            ← 24px padding, optional toggle
      Grid or VStack      ← 32px gap
        TextControl / SelectControl / etc.
    Divider              ← 32px / 64px margin
    ActionCard
  .newspack-buttons-card  ← 64px margin, 16px gap
    Button (primary)
```

--------------------------------

### Webhook POST Payload Example

Source: https://context7.com/automattic/newspack-plugin/llms.txt

This is an example of the JSON payload structure sent to a configured webhook endpoint when a data event occurs.

```json
{
  "action":    "reader_registered",
  "timestamp": 1714000000,
  "client_id": "abc123",
  "data": {
    "user_id": 42,
    "email":   "jane@example.com",
    "metadata": { "utm_source": "homepage" }
  }
}
```

--------------------------------

### Form Group Layout Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Demonstrates how to structure a form group using Grid or VStack within a Card or ActionCard, adhering to the spacing scale for controls.

```jsx
Form group: Use `Grid columns={4}` (or VStack) with TextControl, SelectControl, CheckboxControl, etc. inside a Card or ActionCard; spacing between controls follows the [spacing scale](#spacing-scale-design-system) (e.g. 16px for related rows).
```

--------------------------------

### Imperative Action Confirmation

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/confirm-dialog/README.md

This example demonstrates how to use both `when` and `isOpen` props to guard both navigation and an imperative action. `isOpen` triggers the dialog immediately, for instance, on a button click.

```jsx
const [ pendingAction, setPendingAction ] = useState( null );
<ConfirmDialog
	when={ hasUnsavedChanges }
	isOpen={ !! pendingAction }
	confirmButtonText="Discard changes"
	isDestructive
	hideTitle
	onConfirm={ () => {
		pendingAction?.();
		setPendingAction( null );
	} }
	onCancel={ () => setPendingAction( null ) }
>
	You have unsaved changes that will be lost. Discard changes?
</ConfirmDialog>
```

--------------------------------

### Color Utility Example

Source: https://github.com/automattic/newspack-plugin/blob/trunk/src/newspack-ui/UTILITY_CLASSES.md

Sets the text color to a muted shade using the neutral color scale.

```html
<p class="newspack-ui__color--neutral-60">Muted text</p>
```

--------------------------------

### Handoff to a Specific URL

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/handoff/README.md

Use the `url` prop to navigate to any WordPress admin URL. No additional plugin installation is required for this functionality.

```jsx
<Handoff url="/wp-admin/admin.php?page=newspack-dashboard#/">
    Go to Dashboard
</Handoff>
```

--------------------------------

### Newspack::instance()

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Provides access to the singleton instance of the main Newspack class, which handles plugin initialization and hook registration. It also includes utility methods for checking setup status, debug mode, and retrieving plugin URLs.

```APIDOC
## Newspack::instance()

### Description
Returns the single instance of the main `Newspack` class, which initializes constants, loads all includes, and wires WordPress action/filter hooks on construction.

### Usage
```php
// newspack.php — called automatically on plugin load
Newspack::instance();

// Check if the initial setup wizard has been completed
if ( Newspack::is_setup_complete() ) {
    // Site is configured — safe to run revenue features
}

// Enable debug mode by defining WP_NEWSPACK_DEBUG in wp-config.php
// define( 'WP_NEWSPACK_DEBUG', true );
if ( Newspack::is_debug_mode() ) {
    // Extra logging is active; reset options via ?newspack_reset=reset
}

// Get the plugin's base URL (used to enqueue assets)
$plugin_url = Newspack::plugin_url();
// e.g. https://example.com/wp-content/plugins/newspack-plugin

// Enqueue shared JS/CSS commons bundle from any wizard or admin page
Newspack::load_common_assets();
// Registers and enqueues: dist/commons.js, dist/commons.css, dist/admin.css
```
```

--------------------------------

### Using Form Controls and Layout Components

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

An example demonstrating the usage of RangeControl and CheckboxControl within an ActionCard, utilizing HStack for horizontal layout. Requires importing components from '@wordpress/components' and local packages.

```jsx
import {
	CheckboxControl,
	ExternalLink,
	__experimentalHStack as HStack,
	RangeControl,
} from '@wordpress/components';
import { ActionCard, Card } from '../../../../../packages/components/src';

<ActionCard title="Settings">
	<HStack>
		<RangeControl
			label={ __( 'Value', 'newspack-plugin' ) }
			value={ config.value }
			onChange={ value => updateConfig( 'value', value ) }
		/>
		<CheckboxControl
			label={ __( 'Enable', 'newspack-plugin' ) }
			checked={ config.enabled }
			onChange={ value => updateConfig( 'enabled', value ) }
		/>
	</HStack>
</ActionCard>

```

--------------------------------

### Newspack Activation Hook

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Register a callback function to the `newspack_activation` hook, which executes immediately after the Newspack plugin is activated. Useful for one-time setup tasks.

```php
// Hooks available after activation / deactivation
add_action( 'newspack_activation', function() {
    // Plugin just activated — run any one-time setup
} );
```

--------------------------------

### Get My Account Menu Item

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Return an array with 'slug', 'label', and 'position' to add a tab to the WooCommerce My Account page. Defaults to `null` (no tab).

```php
public function get_my_account_menu_item()
```

--------------------------------

### Sample newspack_collection_ctas Post Meta Structure

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/collections/README.md

Provides an example of the expected structure for the 'newspack_collection_ctas' post meta field, which accepts an array of CTA objects. Each object can be a link or an attachment, requiring 'type', 'label', and 'url' or 'id' respectively.

```php
[
   {
      "type": "link",
      "label": "Digital Edition",
      "url": "https://example.com"
   },
   {
      "type": "attachment",
      "label": "Download PDF",
      "id": 123
   }
]
```

--------------------------------

### Functional Component Example (Correct)

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Demonstrates the preferred structure for new Newspack components using a functional React component. Ensure all user-facing strings are wrapped in translation functions.

```jsx
// ✅ CORRECT - example from the Divider component
/**
 * Divider
 */

/**
 * Internal dependencies
 */
import './style.scss';

/**
 * External dependencies
 */
import classNames from 'classnames';

const Divider = ( { alignment = 'none', className = undefined, marginBottom = 64, marginTop = 64, variant = 'default', ...otherProps } ) => {
	const classes = classNames(
		'newspack-divider',
		className,
		alignment && `newspack-divider--alignment-${ alignment }`,
		variant && `newspack-divider--variant-${ variant }`
	);

	const style = {
		'--divider-margin-bottom': typeof marginBottom === 'number' ? `${ marginBottom }px` : marginBottom,
		'--divider-margin-top': typeof marginTop === 'number' ? `${ marginTop }px` : marginTop,
	};

	return <hr className={ classes } style={ style } { ...otherProps } />;
};

export default Divider;
```

--------------------------------

### Backend/Admin Color Usage Example (SCSS)

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/colors/DEVELOPMENT.md

Demonstrates overriding the WordPress admin accent color with Newspack's primary color and using WordPress base styles for other UI elements like background, border, and text.

```scss
@use "~@wordpress/base-styles/colors" as wp-colors;
@use "../../colors/colors.module" as colors;

:root {
	// Override WordPress accent color
	--wp-admin-theme-color: #{colors.$primary-600};
}

.component {
	// Use WordPress colors for everything else
	background: wp-colors.$gray-100;
	border: 1px solid wp-colors.$gray-300;
	color: wp-colors.$gray-900;

	&:hover {
		background: wp-colors.$gray-200;
	}
}
```

--------------------------------

### Importing Experimental Components from @wordpress/components

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Demonstrates how to import experimental components like HStack, VStack, and NumberControl from '@wordpress/components'. Includes the necessary eslint disable comment for unsafe APIs.

```jsx
import {
	__experimentalHStack as HStack,
	__experimentalNumberControl as NumberControl,
	__experimentalVStack as VStack,
	ExternalLink,
} from '@wordpress/components';

```

--------------------------------

### Get reCAPTCHA Site Key and Version

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Retrieve the reCAPTCHA site key for front-end script localization or get the configured version ('v3' or 'v2_invisible').

```php
// Retrieve just the site key (for front-end script localization)
$site_key = \Newspack\Recaptcha::get_site_key();
$version  = \Newspack\Recaptcha::get_setting( 'version' ); // 'v3' or 'v2_invisible'
```

--------------------------------

### Get Registration Key

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Override to implement custom registration key schemes. The default uses HMAC-SHA256.

```php
public function get_registration_key()
```

--------------------------------

### Plugin_Manager

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Manages the lifecycle of recommended and required third-party plugins. Provides operations to install, activate, and deactivate plugins.

```APIDOC
## Plugin_Manager

### Description
Tracks and manages the lifecycle of recommended and required third-party plugins (Akismet, Jetpack, Google Site Kit, WooCommerce, etc.), providing install/activate/deactivate operations via the Newspack wizard interface and a REST API.

### Methods

#### `get_managed_plugins()`

**Description:** Lists all managed plugins along with their current status.

**Returns:** An associative array where keys are plugin slugs and values are arrays containing plugin information (`Name`, `Description`, `Status`, `Download`).

```php
$plugins = \Newspack\Plugin_Manager::get_managed_plugins();
foreach ( $plugins as $slug => $info ) {
    /*
     * $info = [
     *   'Name'        => 'Jetpack',
     *   'Description' => '...',
     *   'Status'      => 'active',   // or 'inactive', 'uninstalled'
     *   'Download'    => 'wporg',    // or specific zip URL
     * ]
     */
}
```

#### `get_managed_plugins_status()`

**Description:** Retrieves the full status (active, inactive, uninstalled) of all managed plugins.

**Returns:** An array containing the status of each managed plugin.

```php
$statuses = \Newspack\Plugin_Manager::get_managed_plugins_status();
```

#### `activate( string $slug )`

**Description:** Activates a plugin specified by its slug.

**Parameters:**

- **`$slug`** (string) - Required - The unique slug of the plugin to activate (e.g., 'jetpack').

**Returns:** A success status or a `WP_Error` object on failure.

**Example:**

```php
$result = \Newspack\Plugin_Manager::activate( 'jetpack' );
if ( is_wp_error( $result ) ) {
    error_log( $result->get_error_message() );
}
```

#### `install( string $slug )`

**Description:** Installs (downloads and activates) a plugin specified by its slug.

**Parameters:**

- **`$slug`** (string) - Required - The unique slug of the plugin to install (e.g., 'co-authors-plus').

**Returns:** A success status or a `WP_Error` object on failure.

**Example:**

```php
$result = \Newspack\Plugin_Manager::install( 'co-authors-plus' );
```

#### `static::$required_plugins`

**Description:** A static property containing an array of slugs for all required plugins.

**Example:**

```php
$required = \Newspack\Plugin_Manager::$required_plugins;
// ['akismet', 'jetpack', 'pwa', 'google-site-kit', 'newspack-blocks', ...]
```
```

--------------------------------

### Handoff to a Managed Plugin

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/handoff/README.md

Use the `plugin` prop to hand off to a Newspack-managed plugin. The button will be disabled if the specified plugin is not installed or inactive.

```jsx
<Handoff plugin="jetpack">
    Configure Jetpack
</Handoff>
```

--------------------------------

### Initialize Reader Activation System (RAS)

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Call Reader_Activation::init() to hook authentication, cookie management, and other RAS features. Use Reader_Activation::is_enabled() to check if RAS is active. Programmatically register readers with register_reader(), check if a user is a reader with is_user_reader(), manage settings with get_setting()/update_setting()/get_settings(), retrieve newsletter lists with get_registration_newsletter_lists(), and activate campaign presets with activate().

```php
// Check if RAS is active (enabled from the Newspack dashboard)
if ( \Newspack\Reader_Activation::is_enabled() ) {

    // Register a new reader programmatically
    $result = \Newspack\Reader_Activation::register_reader(
        'jane@example.com',  // email
        'Jane',              // display name (optional)
        true,                // authenticate immediately
        [
            'registration_method' => 'custom_form',
            'utm_source'          => 'homepage_banner',
        ]
    );
    // $result: WP_User on success, WP_Error on failure

    // Check whether a WP_User is classified as a "reader" (not an editor/admin)
    $user = get_user_by( 'email', 'jane@example.com' );
    $is_reader = \Newspack\Reader_Activation::is_user_reader( $user ); // true/false

    // Get/set a single RAS setting
    $sender_name = \Newspack\Reader_Activation::get_setting( 'sender_name' );
    \Newspack\Reader_Activation::update_setting( 'sender_name', 'The Daily Bugle' );

    // Retrieve all current RAS settings as key => value array
    $settings = \Newspack\Reader_Activation::get_settings();

    // Get newsletter lists to present at reader registration
    $lists = \Newspack\Reader_Activation::get_registration_newsletter_lists();
    foreach ( $lists as $list ) {
        // $list['id'], $list['title'], $list['checked']
    }

    // Activate the RAS campaign presets (requires Newspack Campaigns plugin)
    $activated = \Newspack\Reader_Activation::activate();
    if ( is_wp_error( $activated ) ) {
        error_log( $activated->get_error_message() );
    }
}
```

--------------------------------

### Importing Newspack Components as npm Package

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

If newspack-components is installed as a dependency in another plugin, import components using the package name 'newspack-components'.

```jsx
// ✅ CORRECT - When installed as npm package
import { Button, Card, Notice } from 'newspack-components';
```

--------------------------------

### Build Project Assets

Source: https://github.com/automattic/newspack-plugin/blob/trunk/README.md

Execute this command for a single compilation run of SCSS and JS files.

```bash
npm run build
```

--------------------------------

### Get Full Status of Managed Plugins

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Obtain the comprehensive status for all plugins managed by Newspack, encompassing active, inactive, and uninstalled states.

```php
// Get the full status of all plugins (active, inactive, uninstalled)
$statuses = 
Newspack\
Plugin_Manager::get_managed_plugins_status();
```

--------------------------------

### Support Frontend Registration

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Return `true` to expose the integration's registration key to the frontend and accept it on the registration endpoint.

```php
public function supports_frontend_registration()
```

--------------------------------

### Get reCAPTCHA Settings via REST API

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Use this curl command to retrieve the current reCAPTCHA configuration. Requires the 'manage_options' capability.

```bash
# GET current reCAPTCHA settings (requires manage_options capability)
curl -X GET https://example.com/wp-json/newspack/v1/recaptcha \
  -H "X-WP-Nonce: <nonce>"
# Response:
# {
#   "use_captcha": true,
#   "site_key": "6Lc...",
#   "version": "v3"
# }
```

--------------------------------

### Basic PluginToggle Usage

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/plugin-toggle/README.md

Use this snippet to display ActionCards for WooCommerce and Instant Articles with default Handoff links.

```jsx
<PluginToggle
	plugins={ {
		wocommerce: true,
		'fb-instant-articles': true,
	} }
/>
```

--------------------------------

### Standard Import Pattern for Dependencies

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Follow this import order for external, WordPress, and internal dependencies, with each group separated by a blank line and a JSDoc comment.

```jsx
/**
 * External dependencies
 */
import classnames from 'classnames';

/**
 * WordPress dependencies
 */
import { CheckboxControl, ExternalLink } from '@wordpress/components';
import { __ } from '@wordpress/i18n';
import { useState } from '@wordpress/element';

/**
 * Internal dependencies
 */
import {
	ActionCard,
	Button,
	Card,
	Notice,
	TextControl,
} from '../../../../../packages/components/src';
```

--------------------------------

### Get Available Incoming Fields

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Return an array of `Incoming_Field` objects representing the schema available for pulling data. This is required for integrations that support pulling.

```php
public function get_available_incoming_fields()
```

--------------------------------

### Define Allowed Plugin Editors Constant

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Configure the `NEWSPACK_ALLOWED_PLUGIN_EDITORS` constant in `wp-config.php` to restrict access to plugin editor and installer screens to specific user IDs.

```php
// Restrict plugin editor/installer screens to specific user IDs
define( 'NEWSPACK_ALLOWED_PLUGIN_EDITORS', [ 1, 5, 12 ] );
```

--------------------------------

### Divider Component Usage

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/divider/README.md

Demonstrates how to import and use the Divider component with various prop configurations.

```APIDOC
## Divider Component

Horizontal rule component with alignment, variant, and margin options.

### Props

| Prop | Type | Default | Description |
|---|---|---|---|
| `alignment` | `'full-width'` \| `'none'` | `'none'` | `full-width` breaks out of the container to span the viewport; `none` stays within the container. |
| `className` | `string` | — | Additional CSS class. |
| `marginBottom` | `number` \| `string` | `64` | Bottom margin (e.g. `64` or `"2rem"`). Capped at 32px on viewports < 783px. |
| `marginTop` | `number` \| `string` | `64` | Top margin (e.g. `64` or `"2rem"`). Capped at 32px on viewports < 783px. |
| `variant` | `'default'` \| `'primary'` \| `'secondary'` \| `'tertiary'` | `'default'` | Line color: `default` uses `$gray-300`; `primary` uses the admin theme color (`--wp-admin-theme-color`); `secondary` uses `$gray-900`; `tertiary` uses `$gray-100`. |

### Usage Examples

```jsx
import { Divider } from 'newspack-components';

// Basic Divider
<Divider />

// Divider with full-width alignment and primary variant
<Divider alignment="full-width" variant="primary" />

// Divider with custom margins and secondary variant
<Divider marginBottom={ 48 } marginTop={ 32 } variant="secondary" />
```
```

--------------------------------

### Check if All Required Plugins are Active

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Verify that all plugins designated as required by Newspack are currently active on the WordPress installation. Access the list of required plugin slugs.

```php
// Check if all required plugins are active
$required = 
Newspack\
Plugin_Manager::$required_plugins;
// ['akismet', 'jetpack', 'pwa', 'google-site-kit', 'newspack-blocks', ...] 
```

--------------------------------

### Check if Integration is Set Up

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Determine if external prerequisites for the integration are configured. Defaults to `true` and is used by the Integrations UI.

```php
public function is_set_up()
```

--------------------------------

### PluginToggle with Page Refresh

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/plugin-toggle/README.md

Enable page reloading after installing or uninstalling WooCommerce by setting `shouldRefreshAfterUpdate` to true. Custom links are also configured for Instant Articles.

```jsx
<PluginToggle
	plugins={ {
		wocommerce: {
			shouldRefreshAfterUpdate: true,
		},
		'fb-instant-articles': {
			actionText: __( 'Configure Instant Articles' ),
			href: '/wp-admin/admin.php?page=newspack-dashboard',
		},
	} }
/>
```

--------------------------------

### PluginToggle with Custom Links

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/plugin-toggle/README.md

Configure custom text and URLs for the Handoff links associated with WooCommerce and Instant Articles.

```jsx
<PluginToggle
	plugins={ {
		wocommerce: {
			actionText: __( 'Use WooCommerce' ),
			href: '/wp-admin/admin.php?page=newspack-dashboard',
		},
		'fb-instant-articles': {
			actionText: __( 'Configure Instant Articles' ),
			href: '/wp-admin/admin.php?page=newspack-dashboard',
		},
	} }
/>
```

--------------------------------

### Class Component Example (Avoid)

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/DEVELOPMENT.md

Illustrates an older class-based component structure, which should be avoided for new Newspack components. Prefer functional components for modern development.

```jsx
// ❌ WRONG – Example from the older `Popover` component
/**
 * WordPress dependencies
 */
import { Popover as BaseComponent } from '@wordpress/components';
import { Component } from '@wordpress/element';

/**
 * Internal dependencies
 */
import './style.scss';

/**
 * External dependencies
 */
import classnames from 'classnames';

/**
 * Popover
 */
class Popover extends Component {
	/**
	 * Render
	 */
	render() {
		const { className, padding, ...otherProps } = this.props;
		const classes = classnames( 'newspack-popover', padding && 'newspack-popover__padding-' + padding, className );
		return <BaseComponent className={ classes } { ...otherProps } />;
	}
}

Popover.defaultProps = {
	padding: false,
};

export default Popover;
```

--------------------------------

### Reader_Activation::init()

Source: https://context7.com/automattic/newspack-plugin/llms.txt

Initializes the Reader Activation System (RAS), setting up authentication, cookie management, WooCommerce integration, newsletter sign-ups, and REST routes. It's essential to check `Reader_Activation::is_enabled()` before using RAS features.

```APIDOC
## Reader_Activation::init()

### Description
Initializes the Reader Activation System (RAS), hooking authentication, cookie management, WooCommerce integration, newsletter sign-up, and REST routes. Must call `Reader_Activation::is_enabled()` before relying on any RAS features.

### Usage
```php
// Check if RAS is active (enabled from the Newspack dashboard)
if ( \Newspack\Reader_Activation::is_enabled() ) {

    // Register a new reader programmatically
    $result = \Newspack\Reader_Activation::register_reader(
        'jane@example.com',  // email
        'Jane',              // display name (optional)
        true,                // authenticate immediately
        [
            'registration_method' => 'custom_form',
            'utm_source'          => 'homepage_banner',
        ]
    );
    // $result: WP_User on success, WP_Error on failure

    // Check whether a WP_User is classified as a "reader" (not an editor/admin)
    $user = get_user_by( 'email', 'jane@example.com' );
    $is_reader = \Newspack\Reader_Activation::is_user_reader( $user ); // true/false

    // Get/set a single RAS setting
    $sender_name = \Newspack\Reader_Activation::get_setting( 'sender_name' );
    \Newspack\Reader_Activation::update_setting( 'sender_name', 'The Daily Bugle' );

    // Retrieve all current RAS settings as key => value array
    $settings = \Newspack\Reader_Activation::get_settings();

    // Get newsletter lists to present at reader registration
    $lists = \Newspack\Reader_Activation::get_registration_newsletter_lists();
    foreach ( $lists as $list ) {
        // $list['id'], $list['title'], $list['checked']
    }

    // Activate the RAS campaign presets (requires Newspack Campaigns plugin)
    $activated = \Newspack\Reader_Activation::activate();
    if ( is_wp_error( $activated ) ) {
        error_log( $activated->get_error_message() );
    }
}
```
```

--------------------------------

### ConfirmDialog Component Usage

Source: https://github.com/automattic/newspack-plugin/blob/trunk/packages/components/src/confirm-dialog/README.md

Examples demonstrating how to use the ConfirmDialog component to guard navigation when a form has unsaved changes, and how to use it for larger modals with custom sizes.

```APIDOC
## ConfirmDialog Component Usage

### Description
Examples demonstrating how to use the ConfirmDialog component to guard navigation when a form has unsaved changes, and how to use it for larger modals with custom sizes.

### Usage

```jsx
import { ConfirmDialog } from 'newspack-components';

// Guard navigation when a form has unsaved changes.
// The dialog appears automatically when the user tries to navigate away.
<ConfirmDialog
	when={ hasUnsavedChanges }
	title="Unsaved changes"
	confirmButtonText="Leave anyway"
	cancelButtonText="Stay"
	isDestructive
>
	You have unsaved changes. Are you sure you want to leave?
</ConfirmDialog>

// Larger modal with a custom size
<ConfirmDialog
	when={ hasUnsavedChanges }
	size="medium"
	title="Discard changes?"
	confirmButtonText="Discard"
	cancelButtonText="Keep editing"
>
	Your changes will be lost if you leave this page.
</ConfirmDialog>
```
```

--------------------------------

### Check Integration Sync Readiness

Source: https://github.com/automattic/newspack-plugin/blob/trunk/includes/reader-activation/integrations/README.md

Verify if the integration is configured and ready for data synchronization. Returns a boolean on success or a `WP_Error` object if `$return_errors` is true.

```php
public function can_sync( $return_errors = false )
```