=== FansPaysite ===
Contributors: videowhisper
Author: VideoWhisper.com
Author URI: https://videowhisper.com
Requires at least: 5.1
Tested up to: 6.8
Requires PHP: 7.4
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Stable tag: 2.6

FansPaysite is a creator-focused WordPress theme with dark/light mode, skins, a palette manager, footer menu support, Fomantic UI styling, flexible layouts, and plugin-friendly integration hooks.

== Description ==
FansPaysite is a mobile-first WordPress theme for creator, membership, community, and media sites. It includes flexible left-sidebar and top-bar layouts, dark and light modes, skin presets, a palette manager for the six core theme colors, icon-driven menus, footer menu support, block editor support, reusable patterns, Elementor-compatible page templates, and theme integrations for WooCommerce and BuddyPress.

Key features:
- Three archive display modes: Classic, Fullpage, and Boxes
- Appearance > FansPaysite admin page with Skins, Palettes, Advanced, and Integration tabs
- Dark/light/auto mode with user preference persistence
- Palette manager with built-in presets, apply/save/delete actions, and skin-derived palettes
- Typography presets: System, Inter, Nunito, Lato, Roboto, Open Sans, Poppins, Georgia, Merriweather
- Footer menu and copyright area designed to remain reachable on mobile layouts
- Optional CDN loading for bundled libraries, disabled by default for WordPress.org-friendly local bundling
- Conditional loading for theme WooCommerce and BuddyPress integration CSS
- Shared Fomantic UI component handles and helpers for plugin developers
- Font Awesome icon picker for menu items
- Accessibility and keyboard-navigation improvements for menus and fullpage archives

=== Archive Display Modes ===

The theme offers three distinct ways to display post archives (blog, category, search results):

1. Classic - Enhanced card layout with thumbnail, title, excerpt, metadata, and plugin action hooks.
2. Fullpage - Social media style snap-scroll view where each post fills the viewport.
3. Boxes - Responsive grid cards with author avatar, relative time, and post format badges.

All modes support:
- Core post formats
- Auto-pagination on scroll
- Comment count display
- Extension hooks for plugin metadata and actions
- More button for full post view

Configure via Appearance > Customize > FansPaysite Theme > Post Display > Archive Display Mode.

== Theme Structure ==

=== File Organization ===
fanspaysite/
  style.css            - Main stylesheet, theme metadata, layout CSS, design tokens
  functions.php        - Theme setup, sidebar registration, body classes, integration context
  header.php           - Sidebar or top-bar header output
  footer.php           - Footer, right sidebar, wp_footer
  index.php            - Archive entry point
  page.php             - Single page template
  single.php           - Single post template
  comments.php         - Comment list and form
  editor-style.css     - Block editor styles
  screenshot.png       - Theme screenshot for WP admin
  default.png          - Default post thumbnail fallback

  inc/
    customizer.php     - Customizer settings for layout, colors, typography, post display, footer
    enqueue.php        - Theme asset loading, bundled/CDN library resolver, shared Fomantic helpers
    menu.php           - Menu walkers, icon picker, icon mappings
    mode.php           - Theme mode logic, palette token export, Google Fonts loading, AJAX preference updates
    admin.php          - Appearance > FansPaysite admin page, skins, palettes, Advanced tab, Integration tab
    blocks.php         - Block patterns and styles
    comments.php       - Custom comment callback
    woocommerce.php    - WooCommerce support and conditional theme WooCommerce CSS
    buddypress.php     - BuddyPress support and conditional theme BuddyPress CSS

  template-parts/
    archive/           - Archive mode templates
    content-*.php      - Content partials

  js/
    archive.js         - Fullpage archive behavior and auto-pagination
    menu.js            - Menu dropdown behavior and mobile handling
    theme.js           - Frontend theme mode switcher
    fa-picker.js       - Menu icon picker initialization

  css/
    woocommerce.css    - Theme WooCommerce integration styles
    buddypress.css     - Theme BuddyPress integration styles

  lib/
    fa/                - Font Awesome Free 7.1.0
    fa-picker/         - Font Awesome Icon Picker 3.2.0
    fomantic/          - Fomantic UI 2.9.4 component bundle

  .docs/
    developer.md       - Internal developer reference
    integration.md     - Extended plugin integration guide for agents and developers
    performance.md     - Performance notes

=== Architecture Overview ===

Layout System:
  The theme uses a flexbox-based full-viewport layout with two main variants.

  Left Sidebar Layout:
    .site-wrapper (flex row, 100vh)
      .site-sidebar
      .site-content
      .site-sidebar-right

  Top Bar Layout:
    .site-wrapper (flex column, 100vh)
      .site-topbar
      .site-topbar-expanded
      .site-content-wrapper

Theme Mode:
  The active mode is resolved in this order:
  1. Logged-in user preference stored in user meta
  2. Logged-out visitor cookie
  3. Site default from Customizer

Typography:
  The theme supports multiple typography presets. Google Fonts are only requested
  for presets that need them, while system and serif stacks stay local.

Menus:
  Custom menu walkers render icon-based menus for both layout modes. Menu items
  can use a custom icon class, an automatic title-to-icon mapping, or a fallback icon.

Admin Page:
  Appearance > FansPaysite includes:
  - Skins tab for applying and saving skins
  - Palettes tab for applying and saving six-color palettes, including built-in skin palettes
  - Advanced tab for optional CDN loading of bundled libraries
  - Integration tab with public plugin developer documentation

Bundled Libraries:
  - Fomantic UI 2.9.4 loaded per component instead of the monolithic bundle
  - Font Awesome Free 7.1.0
  - Font Awesome Icon Picker 3.2.0 for menu icon selection in wp-admin

Performance Notes:
  - Theme WooCommerce CSS only loads on WooCommerce screens
  - Theme BuddyPress CSS only loads on BuddyPress screens
  - Google Fonts are output asynchronously with resource hints
  - Bundled libraries can optionally load from jsDelivr CDN when enabled in Advanced settings

== Plugin Integration ==

FansPaysite includes a public integration surface for plugin developers.

=== Admin Documentation ===

Open:
`wp-admin/themes.php?page=fanspaysite&tab=integration`

The Integration tab documents:
- current mode/layout/skin context
- exported CSS tokens
- shared Fomantic handles
- available helper functions
- integration hooks for skins, archive cards, breadcrumbs, and admin docs

=== Theme Mode Support ===

Plugins should support dark/light mode by using the theme selectors and CSS variables instead of hard-coded colors.

Recommended selectors:
- `html[data-theme="light"]`
- `html[data-theme="dark"]`
- `body.inverted`
- `.ui.inverted`

Recommended CSS variables:
- `--fanspaysite-background-color`
- `--fanspaysite-text-color`
- `--fanspaysite-link-color`
- `--fanspaysite-light-background-color`
- `--fanspaysite-light-text-color`
- `--fanspaysite-light-link-color`
- `--fanspaysite-dark-background-color`
- `--fanspaysite-dark-text-color`
- `--fanspaysite-dark-link-color`

Legacy aliases are also available:
- `--background-color`
- `--text-color`
- `--link-color`

Example:

```css
.my-plugin-panel {
  background: var(--fanspaysite-background-color, var(--background-color, #fff));
  color: var(--fanspaysite-text-color, var(--text-color, #333));
  border: 1px solid color-mix(in srgb, var(--fanspaysite-link-color, var(--link-color, #77145d)) 20%, transparent);
}

html[data-theme="dark"] .my-plugin-panel {
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.35);
}
```

=== Skin Support ===

Skins control:
- layout
- menu behavior
- default theme mode
- light and dark palette values
- archive display mode
- several auxiliary theme settings

Useful skin hooks:
- `fanspaysite_builtin_skins` - Register plugin-aware built-in skins
- `fanspaysite_all_skins` - Inspect or extend all available skins
- `fanspaysite_capture_skin_settings` - Add plugin settings when a user saves the current configuration as a skin
- `fanspaysite_skin_applied` - Sync plugin options when a FansPaysite skin is applied

Example:

```php
add_filter( 'fanspaysite_builtin_skins', function( $skins ) {
  $skins['my-plugin-midnight'] = array(
    'name'            => __( 'My Plugin Midnight', 'my-plugin' ),
    'description'     => __( 'Dark preset aligned with My Plugin screens.', 'my-plugin' ),
    'layout'          => 'top-bar',
    'burger_menu'     => 'auto',
    'menu_display'    => 'auto',
    'submenu_display' => 'auto',
    'submenu_hover'   => 'auto',
    'default_mode'    => 'dark',
    'archive_display' => 'classic',
    'colors'          => array(
      'light_bg'   => '#ffffff',
      'light_text' => '#1f2933',
      'light_link' => '#0f6cbd',
      'dark_bg'    => '#111827',
      'dark_text'  => '#f9fafb',
      'dark_link'  => '#60a5fa',
    ),
    'custom_css'      => '',
    'is_builtin'      => true,
  );

  return $skins;
} );
```

=== Fomantic UI Support ===

FansPaysite ships and registers a shared subset of Fomantic components so plugins can reuse them instead of enqueuing duplicate copies.

Shared style handles:
- `fomantic-site`
- `fomantic-reset`
- `fomantic-menu`
- `fomantic-dropdown`
- `fomantic-button`
- `fomantic-divider`
- `fomantic-image`
- `fomantic-label`
- `fomantic-comment`
- `fomantic-header`
- `fomantic-segment`
- `fomantic-form`
- `fomantic-message`
- `fomantic-transition`

Shared script handles:
- `fomantic-site`
- `fomantic-transition`
- `fomantic-dropdown`

Plugin helper:
- `fanspaysite_enqueue_fomantic_components()`

Example:

```php
add_action( 'wp_enqueue_scripts', function() {
  if ( function_exists( 'fanspaysite_enqueue_fomantic_components' ) ) {
    fanspaysite_enqueue_fomantic_components(
      array( 'segment', 'form', 'message', 'button' ),
      array()
    );
  }
}, 20 );
```

If a plugin needs Fomantic modules not bundled locally by the theme, it should enqueue those modules itself with plugin-namespaced handles while still styling against the exported theme tokens.

=== PHP Helpers ===

Useful helper functions:
- `fanspaysite_get_current_theme_mode()` - Returns `light`, `dark`, or `auto`
- `fanspaysite_get_theme_color_tokens()` - Returns the light/dark palette arrays
- `fanspaysite_get_theme_integration_context()` - Returns current skin, layout, menu mode, color tokens, and shared asset handles
- `fanspaysite_get_fomantic_style_handles()` - Returns the shared style handles
- `fanspaysite_get_fomantic_script_handles()` - Returns the shared script handles

=== Additional Hooks ===

- `fanspaysite_breadcrumb` - Output breadcrumbs before the main content area
- `fanspaysite_post_card_before`
- `fanspaysite_post_card_meta`
- `fanspaysite_post_card_actions`
- `fanspaysite_post_card_after`
- `fanspaysite_integration_tab_content` - Add plugin-specific notes to the Integration admin tab

=== Agent / Internal Reference ===

For a more extensive agent-oriented guide, see:
`.docs/integration.md`

== Customizer Settings Reference ==

Section: FansPaysite Theme
  fanspaysite_layout                    - Layout: left-sidebar/top-bar
  fanspaysite_default_theme_mode        - Default mode: light/dark/auto
  fanspaysite_show_theme_mode_switcher  - Show frontend switcher
  fanspaysite_menu_display_mode         - Main menu display mode
  fanspaysite_submenu_display_mode      - Secondary menu display mode
  fanspaysite_submenu_hover             - Submenu hover behavior
  fanspaysite_sticky_header             - Sticky menu bar / top bar
  fanspaysite_content_width             - Content width: default/wide/boxed
  fanspaysite_show_right_sidebar        - Right sidebar visibility: auto/yes/no
  fanspaysite_font_preset               - Typography preset selection
  fanspaysite_archive_display           - Archive mode: classic/fullpage/boxes
  default_post_thumbnail                - Default thumbnail image
  display_title                         - Show post title
  display_category                      - Show post category
  display_tags                          - Show post tags
  display_date                          - Show post date
  display_author                        - Show post author
  light_mode_background_color           - Light background color
  light_mode_text_color                 - Light text color
  light_mode_link_color                 - Light link color
  dark_mode_background_color            - Dark background color
  dark_mode_text_color                  - Dark text color
  dark_mode_link_color                  - Dark link color

== License ==
FansPaysite WordPress Theme, Copyright 2024 VideoWhisper.com .
FansPaysite is distributed under the terms of the GNU GPL.

== Frequently Asked Questions ==

= How can I change the icons in the menu? =
Open Appearance > Menus, expand a menu item, and edit the FansPaysite icon field. The built-in icon picker can help select a Font Awesome class.

= How do I switch skins or layouts? =
Go to Appearance > FansPaysite. You can apply built-in skins, save your current settings as a custom skin, or use the Customizer for layout and display controls.

= How can a plugin support FansPaysite dark/light mode and styling? =
Use the exported `--fanspaysite-*` CSS variables, the `html[data-theme]` selectors, and the helpers/hooks documented in Appearance > FansPaysite > Integration.

= Can a plugin register or react to skins? =
Yes. Use `fanspaysite_builtin_skins`, `fanspaysite_capture_skin_settings`, and `fanspaysite_skin_applied`.

= Can plugins reuse the theme Fomantic assets? =
Yes. Use `fanspaysite_enqueue_fomantic_components()` and the shared `fomantic-*` handles when the theme already bundles the components you need.

= Can I load bundled libraries from a CDN? =
Yes. Go to Appearance > FansPaysite > Advanced and enable CDN loading. It is disabled by default so the theme stays compatible with WordPress repository expectations and local/self-contained setups.

= Does the theme support WooCommerce and BuddyPress? =
Yes. FansPaysite includes theme integration styles for both and only loads those styles on relevant screens.

= Does this require a separate plugin? =
No. The theme can be used on its own, though it can complement creator, community, commerce, and membership plugins.

= How can I get support or customizations? =
You can get support, configuration assistance, and customization services from VideoWhisper: https://consult.videowhisper.com

== Upgrade Notice ==

= 2.6 =
Improves FansPaysite dark/light mode handling for inverted Fomantic UI content and adds frontend Developer Mode diagnostics.

= 2.5 =
Adds an optional footer legal-links menu and a compact expandable light/dark/system mode selector.

= 2.4 =
Adds optional admin dark mode with light/dark/system presets, controllable per-user from the WP toolbar.

= 2.3 =
Adds a public Integration tab plus documented hooks, helpers, skin filters, and shared Fomantic integration for plugin developers.

== Changelog ==

= 2.6 =
* Theme mode: Preserves authored Fomantic UI inverted elements on load when plugins also apply theme mode scripts
* Theme mode: Uses FansPaysite light/dark palette tokens for inverted and de-inverted Fomantic segments, forms, and cards
* Theme mode: Restores visible dark-mode borders and shadows for regular Fomantic segments/cards using the theme palette
* Admin: Added Advanced > Developer Mode to enable troubleshooting console diagnostics for frontend theme-mode sync

= 2.5 =
* Footer: Added an optional footer menu area for small legal links such as Privacy Policy and Terms of Use
* Footer: Copyright notice now aligns left when the footer menu is active and remains centered otherwise
* Menus: Added a dedicated Footer menu location
* Theme mode: Reworked the frontend light/dark/system control into a compact expandable selector for both left-sidebar and top-bar layouts
* Theme mode: Improved hover behavior so the compact selector stays open long enough to choose another mode

= 2.4 =
* Admin: Added optional admin dark mode (light/dark/system) controllable from Appearance > FansPaysite > Advanced and the WP toolbar
* Admin: Admin dark mode is opt-in (default off) and persists per-site via an option
* Admin: Dark mode state is saved via AJAX without a page reload

= 2.3 =
* Admin: Added Appearance > FansPaysite > Integration tab with plugin developer documentation
* Developer: Added public CSS tokens for current, light, and dark palette values
* Developer: Added theme integration context helper and shared Fomantic handle helpers
* Developer: Added filters and actions for plugin-aware skins and integration tab extensions
* Docs: Added expanded plugin integration documentation to `readme.txt` and `.docs/integration.md`
* Docs: Corrected public admin page documentation to match the actual available tabs

= 2.2 =
* Typography: Added preset options for Lato, Roboto, Open Sans, Poppins, and Merriweather
* Typography: Fixed top-bar text labels so wider fonts stay centered and avoid awkward left-aligned wraps
* Admin: Added Advanced tab in Appearance > FansPaysite with optional CDN loading for bundled libraries
* Libraries: Updated bundled and CDN-loaded assets to Font Awesome Free 7.1.0, Fomantic-UI 2.9.4, and Font Awesome Icon Picker 3.2.0
* Performance: Theme WooCommerce CSS now loads only on WooCommerce screens
* Performance: Theme BuddyPress CSS now loads only on BuddyPress screens
* Performance: Google Fonts load asynchronously with resource hints when a webfont preset is selected
* Performance: Local Font Awesome bundle now uses font-display: swap for icon fonts

= 2.1 =
* Performance: Fomantic UI loaded as individual components instead of the monolithic bundle
* Performance: FOUC fix by resolving theme mode earlier in the document
* Performance: Font preload for Font Awesome and mobile usability improvements
* Gutenberg: Added theme.json, patterns, and improved editor styling
* Elementor: Added Full Width and Blank Canvas page templates
* Customizer: Added sticky header, content width, right sidebar toggle, font presets, and footer columns
* Footer: Configurable widget columns
